CONTRIBUTING: add some notes about contributions

Signed-off-by: Stephen J Day <stephen.day@docker.com>
klihub · Dec 13, 2016 · 4f04e52 · 4f04e52
1 parent b1f547c
commit 4f04e52
Showing 1 changed file with 60 additions and 0 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,65 @@
 # Contributing
 
+Contributions should be made via pull requests. Pull requests will be reviewed
+by one or more maintainers and merged when acceptable.
+
+This project is in an early state, making the impact of contributions much
+greater than at other stages. In this respect, it is important to consider any
+changes or additions for their future impact more so than their current impact.
+
+## Successful Changes
+
+We ask that before contributing, please make the effort to coordinate with the
+maintainers of the project before submitting large or high impact PRs. This
+will prevent you from doing extra work that may or may not be merged.
+
+PRs that are just submitted without any prior communication will likely be
+summarily closed.
+
+While pull requests are the methodology for submitting changes to code, changes
+are much more likely to be accepted if they are accompanied by additional
+engineering work. While we don't define this explicitly, most of these goals
+are accomplished through communication of the design goals and subsqeuent
+solutions. Often times, it helps to first state the problem before presenting
+solutions.
+
+Typically, the best methods of accomplishing this are to submit an issue,
+stating the problem. This issue can include a problem statement and a
+checklist with requirements. If solutions are proposed, alternatives should be
+listed and eliminated. Even if the criteria for elimination of a solution is
+frivelous, say so.
+
+Larger arcs typically work best with design documents, similar to those found
+in `design/`. These are focused on providing context to the design at the time
+the feature was conceived and can inform future documentation contributions.
+
+## Commit Messages
+
+There are times for one line commit messages and this is not one of them.
+Commit messages should follow best practices, including explaining the context
+of the problem and how it was solved, including in caveats or follow up changes
+required. They should tell the story of the change and provide readers
+understanding of what led to it.
+
+If you're lost about what this even means, please see [How to Write a Git
+Commit Message](http://chris.beams.io/posts/git-commit/) for a start.
+
+In practice, the best approach to maintaining a nice commit message is to
+leverage a `git add -p` and `git commit --amend` to formulate a solid
+changeset. This allows one to piece together a change, as information becomes
+available.
+
+If you squash a series of commits, don't just submit that. Re-write the commit
+message, as if the series of commits was a single stroke of brilliance.
+
+That said, there is no requirement to have a single commit for a PR, as long as
+each commit tells the story. For example, if there is a feature that requires a
+package, it might make sense to have the package in a separate commit then have
+a subsequent commit that uses it.
+
+Remember, you're telling part of the story with the commit message. Don't make
+your chapter wierd.
+
 ## Sign your work
 
 The sign-off is a simple line at the end of the explanation for the patch. Your