Vimtex: Add a Contributing Section

[johnrichardrinehart]

Information regarding the proper procedure for contributing using pull requests (branch-based or fork-based) should be included in the README.

[lervag]

This sounds like a good idea! But I'm not used to writing things like this. I would be happy for some suggestions!

[johnrichardrinehart]

No problem. I can definitely help with this. There are a few things that you'll have to "approve" before I continue.

1. It appears that it's convention to include this information at least in the help file for the plugin vimtex.txt, but I think that's a bad idea. This seems like information that is more relevant on the main project page, which is located at https://github.com/lervag/vimtex, currently. Let me know if you agree/disagree.
2. It seems, also, that you have the choice between accepting pull requests from forked repositories or from a branch in the repository. I am attracted to the branch option because it keeps unnecessary server-side clones (forks) from happening. These, over time, tend to clutter the profiles of those who fork many repositories to fix one or two issues. I would recommend this approach.
3. It might be good to indicate what formatting standards you've adopted when writing vimtex. That would improve the uniformity of the project as other users start to commit. I.e. How do you name variables, how you name functions, what spacing do you use for indentation, how wide can the text span on a single line (80 characters?).
4. What information should be included in the pull request besides the code that is being submitted? You probably, for example, want to know for which issue the pull request is being issued. If the pull request is related to a yet-unreported issue, then you probably want it reported before a pull request is submitted.
5. Think of other things you want contributors to do.

[lervag]

I'll read this later; I'm just wondering what you think about the CONTRIBUTION.md that github proposes. That is, as a method of conveying the contributing section.

[lervag]

Ok, so:

1. I agree that this is more relevant to put on the main project page. I think the CONTRIBUTION.md seems like a good place to put this.
2. I am not sure how a branch model would work for contributions. That is, what does this imply for your workflow? Right now, i think it seems most convenient that people fork the project, then make commits as necessary and open a pull request. After discussing and agreeing on the changes, I will merge and squash.
3. Agreed, this should be added to the contribution description.
4. I think pull requests in general should be described similar to issues, in that they should contain all necessary information for me to understand both why, what and how. I don't feel it is important to open an issue first; if someone notices a bug, but also sees how to fix it, I think it is OK to simply open a pull request. They should of course describe the bug/issue, so that I can consider if the problem is really a problem, and if the fix really resolves the problem.
5. I've lately begun to think that the project has much activity. Personally, I feel that people who open issues, describe problems and help me solve them should all be mentioned as contributors. Without them (i.e. you!), I don't think vimtex would be nearly as good as it is now. Obviously, this is something that I need to do, but I have not decided how best to do this. Perhaps it could be a section of the contribution information?

[johnrichardrinehart]

1. I totally agree. I didn't know about the CONTRIBUTION file that GitHub supports.

2. After some review, it seems that allowing branch-style pull requests has a number of disadvantages. I'll outline the workflow for branch-style pull requests, assuming you already understand the workflow for fork-based pull requests. I think you will decide to avoid pursuing this route, obligating forks of your repository which take up more of GitHub's (free) storage - I'm not complaining.

   1. You (@lervag) make a new branch called features or dev or analogous (let's assumed it's called feature).
   2. I (some developer) clone your repository, but I make sure to only ever work in the feature branch (this would be the stumbling block).
   3. When I am ready to make my pull request, I use GitHub's pull request interface to put my head (some commit or series of commits on the features branch) on top of your base (the master branch).
   4. Upon review, and possibly successful unit testing/CI, it is accepted.

   The disadvantages are obvious. You can not restrict permissions on the branch level. So, this would allow anyone to accidentally/intentionally modify the master branch. While git is designed to accommodate mistakes in the workflow, these sorts of issues are clearly avoidable with fork-based pull requests.



3. I think you should be responsible for authoring the "formatting" section of the CONTRIBUTING file. I'm not familiar with all of your personal formatting/naming considerations (evidenced here)


4. That makes sense. However, the forum of discussion is omitted in this case. By limiting the scope of conversation to two users then you are placing a large degree of confidence in you and the author. This is your decision; however, issues allow the author of the issue or nir's with the issue's author to bring other users into the fold.


5. Are you saying that you want to acknowledge each of the contributors? You are going to have to use your best judgment as to how to do that. You may want (I am not asking) to provide more active contributors more credit. How do you determine how many +1's to give each contributor? Is a one-time issue-raiser worthy of a more prominent mention than a daily pull-requester? Overall, I don't think any of the contributors are asking for acknowledgement. We are here in the issues section and in the commit history. For me, that's acknowledgement enough. @mbrunnen @hubanya @frankier @Konfekt @djt308 @micbou, what are your opinions regarding this last point?

[frankier]

Github forks don't take up more space. See http://githubengineering.com/counting-objects/#your-very-own-fork-of-rails . I'm in favour of the fork model.

[johnrichardrinehart]

Wow, that's great to know! Thanks for the information! Here, here! I second the motion.

[lervag]

Thanks for the input!

1. That's settled, then. :)
2. I'm also in favour of the fork model, so that's also settled.
3. Agreed, I'll write a little bit about this.
4. I agree that serious issues should be discussed openly, and that in some cases, it could be done through an issue. I don't think this will become a problem, really.
5. Nah, I think what I am saying is that I am very happy for contributions. Obviously, it is much easier for me when people are able to both report, investigate and solve issues themselves, but I also very much appreciate the effort that is put into just reporting a problem. I think this deserves some credit, but in the end, what is important for me is to extend gratitude towards the community and to acknowledge that vimtex is not just my own work. Perhaps it is better to leave names out of it (usernames and various IDs are clear from git log and from the issue log), and instead just write a paragraph about this somewhere...

[lervag]

I've added the first version. Feedback is very welcome.

[lervag]

There have been some feedback on the commit fb318d95f9445bf6f32d2fea740660d9378afa58 (thanks!). However, I think it is better to have the discussion here, since it will be easier to find it later.

@fuzzybear3965 suggests to add a section on the help doc style and syntax. This is a good idea, and I will add it.

[lervag]

For reference (quote by @fuzzybear3965 from fb318d9):

Did you want to include a subsection addressing documentation contributions? Specifically, I noted that my first pull request for vimtex was accepted without including basic vim documentation markup (described in :h help-writing). I didn't know that it existed. If you want to include a subsection on documentation contributions, it would be nice if you could point people to that part of the manual so that vimtex documentation can be made more uniform should many authors contribute.

[lervag]

I've updated the contributing file with a comment on updating the documentation. I think the issue can be marked resolved now.