Contributor Guidelines
From Open Melody
Every civilization needs a common language in order to function as a society. Similarly, all groups need a set of guidelines and rules to follow and play by. Our development guidelines are listed below and serve to ensure that our distributed development process operates as smoothly as possible with the least amount of confusion and introduction of problems.
Contents |
Your Local Workflow
Because Git gives you complete power (in your local working directory and repository) to rewrite your entire history and craft your commits, branches and pull requests with exacting standards, there's little use in mandating anything about how you work in your local environment. As stated in the introduction, we don't want to impede a successful workflow. You should work in your local repository in whatever way makes you the most productive.
Our Community Workflow
However, because Melody development is a collaborative effort, the state of your branches and committed code becomes relevant as soon as you push your code to GitHub (where others can see it) and absolutely critical when you issue a pull request to the Melody repository administrators.
These guidelines put the onus on all contributors to do just a little extra work to ensure that the small number of repository administrators are not overly burdened with a significant amount of aggregate work.
Before pushing your code to GitHub, you should do whatever it takes to make sure that your changes are easy to parse and comprehend by the repository administrators and that they can be easily integrated into the main Melody source code.
All pull requests will be vetted against these guidelines. Failure to conform to these guidelines will, at best, cause integration delays and much spirited cursing on the part of the repository administrators. At worst, it will be grounds for a loving rejection, re-education and resubmission.
1. Pull Request Content
1.1 Use the latest Melody code — The branch for which you issue the pull request should be based upon the very latest openmelody/melody code with your changes sitting atop it. Not basing your changes on the latest Melody code will almost certainly result in a quick rejection because there is a greater likelihood of conflicts.
1.2 Never issue a pull request on an active branch - When you issue a pull request there should be no further checkins on the branch that you issued it for unless the subsequent checkins were requested by the repository administrator to resolve issues in the code.
1.3 Give your branch a good name — Most branches should be named after the LightHouse issue they address. A good form to use is "KEY-NNN-TOPIC" where KEY is "lh" (for LightHouse), "bug" or "feat", NNN is the LightHouse ticket number and TOPIC is a short string that aids in identification of the branch and distinguishing it from others.
- Good examples: lh-251-encoding, bug-281-appparams, feat-118-logging
- Bad examples:
- Branches distinguished by number alone: (bug-222, bug-224, bug-218).
- Branches with redundant information in the name like your username or the word 'melody'
1.4 Split a crowded branch — If your topic branch covers more than one topic having commits that relate to more than one conceptual change, bugfix or feature, split it out into at least two branches and as many as it takes to focus each on distinct issues.
2. Commit Documentation
2.1 Always include the relevant LightHouse ticket code — Every commit should relate directly to a case in LightHouse and every commit note should reference this case using the special Lighthouse-formatted code to connect the commit to the bug. The most common forms are include:
-
[#218]or[#218 state:committed]- These are essentially the same -
[#218 state:resolved]- Same as above except the ticket will be resolved after the commit is received
See "How do I update tickets with keywords?" for more details
2.2 Write descriptive and informative commit notes — Your commit note is your explanation to the world about your change and together they create a very important story of our development. These commit notes will be used by the repository admins to understand your changes, by other developers to find out when a particular change occurred and before any release to create a changelog. Because of this you should take a couple of seconds out of your busy schedule to make sure that your description supports these efforts and isn't the software development version of "Uhhhh".
2.3 Link to referenced external resources - If you refer to something in your commit note that exists on the web, please add the URL to make it easy for others to follow along. This includes the URL to the LightHouse ticket if you wish to keep your commit note short and delegate the description to the ticket instead.
2.4 Split large composite commits — Each commit should be easily described by its commit note. The larger your commit, the less likely it is that your commit note will be informative without becoming a novella. If you find yourself in this position or find yourself with a large commit, you should consider splitting it into several commits.
3. Commit Contents
3.1 Always use 4 explicit spaces for a tab — Never, ever, ever use tabs (as in the character). We use 4 spaces in Melody and so will you!
3.2 Squash repetitious or spurious commits — If your branch contains more than a few commits, you should consider whether any of the commits can be squashed together. For example, if you've made the same type of edit to many files but over the course of several commits, you could squash all of those together to make a single commit.
3.3 'Commits should be as small as possible — In general, your commits should be as atomic as possible and also contain the smallest number of changed lines (as viewed through a git diff or commit diff on GitHub) to affect the change you desire. If you're making a functional change to the code, resist the urge to reflow or reformat sections of code you aren't changing and realize that rearrangements usually more than double the number of changed lines.
3.4 Isolate whitespace changes and reformatting commits — If you want to fix whitespace issues or code formatting, make all changes of the sort in a single commit with a short commit note like "Whitespace" or "Reflow of code" or "Perltidied method". Do not make any changes in such commits that might make the code work differently.
3.5 Last Chance for New Code - Before issuing your pull request, check once again to ensure that your changes are based on top of the latest code from openmelody/melody in case there were checkins while you were busy reading this.
