Skip to content

Instantly share code, notes, and snippets.

@LB--

LB--/CONTRIBUTING.md

Last active July 5, 2016 14:48
Show Gist options
  • Save LB--/ce30593b7f26026543354ae3ccf424d5 to your computer and use it in GitHub Desktop.
Save LB--/ce30593b7f26026543354ae3ccf424d5 to your computer and use it in GitHub Desktop.
Download ZIP
My personal contributing guidelines
Raw
CONTRIBUTING.md

git

  • Read the license! Understand that your contribution will exist under the terms of the license and that as a result you may be giving up ownership of your code!
  • Preserve history! Only rebase or squash as told to do so in this guide. We don't care about the way commit graphs look.
  • Every commit must compile! This helps with bisecting, among other things.
  • When adding a new feature, base your work on the oldest commit that will allow your new code to compile and run as intended. This helps with merging specific features into older versions.
  • When fixing bugs, base the fix on the commit that introduced the bug. This helps with merging in bugfixes into older versions for bugfix releases.
  • When changing behavior, base your work on the most recent commit that changed or introduced the behavior. This helps with reverting changes for specially-made old versions, as well as making it easy to trace all the ways something has changed.
  • When removing code, base your work on the most recent commit that changed or introduced it, for the same reason as above.
  • One commit per feature/bugfix/change! If you need to base your work on multiple existing commits, merge the commits needed for your feature/bugfix/change in a separate commit and base your one commit on that.
  • There are (usually) only six kinds of commits: merge, new feature, bugfix, change, deprecation, and removal. If your commit fits into more than one of those categories, it should probably be split into multiple commits.
  • A commit should be the smallest unit of change in order to go from the undesired functionality to the desired functionality, barring special circumstances. It is fine to knock out two birds with one stone if the commit is not divisible by this definition.
  • The first line of commit messages should be able to fill in the blank in the sentence Merging this commit will ________________ without sounding weird. Don't worry about length, but keep it to one sentence.
  • Examples: Add suport for ABC, Fix crash when XYZ, Change ABC to XYZ, Deprecate ABC in favor of XYZ, Remove ABC
  • Whereas in-code comments explain the way code works and why spcific designs and algorithms were chosen, commit message lines after the first should explain why a feature was added, how a bug was discovered and fixed, or why a change is being made.
  • Always merge with --no-ff --no-commit and make sure everything compiles and runs as it should before concluding the merge! Don't be afraid to make changes that only appear in the merge commit - tools exist to view such changes. Don't be afraid to create merge commits with more than two parents - do what is necessary.
  • Merge commit messages: I don't know the best course of action here - for now, just leave the first line as default and in the remaining lines provide any information about why and how you chose to resolve conflicts the way you did, as well as any other necessary changes to make the code compile and run as expected.
  • If you are signing your commits, please try to match formatting and indentation with the rest of the project. If you aren't signing your commits, we'll amend the formatting for you, so don't worry too much about it. (Since formatting doesn't affect the behavior of a program, we don't care about throwing away history about formatting changes, but we don't want to amend signed commits - you have to amend your own signed commits).

GitHub

  • In general follow all the guidelines in the git sction above.
  • If there are one or more open GitHub issues that should be closed upon merging your commit, the second line of the commit message should consist only of the magic text and any further details should start on the third line. Use Closes #00 for new features or removals, Fixes #00 for bugfixes, and Resolves #00 for changes.
  • Make sure you send pull requests to the correct branch, otherwise GitHub's merge detection won't work. (Not to be confused with the feature that detects if the merge can be made automatically via the evil merge button).
  • Pull requests in general shouldn't need much explanation in the description - prefer to explain things in the commit messages as described in the git section above.
  • Never use GitHub's automatic merge button! Always merge on the command line as explained in the git section above.

MarkDown

  • Each sentence should be on its own line.

C++

  • ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment