Updates CONTRIBUTING.md with coding conventions.

metacpan · Oct 8, 2014 · 530d6c4 · 530d6c4
1 parent 193c779
commit 530d6c4
Showing 1 changed file with 49 additions and 1 deletion.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -36,6 +36,55 @@ These links will get you going quickly:
   * [API (back end) bug list](https://github.com/CPAN-API/cpan-api/issues)
   * [Wishlist](https://github.com/CPAN-API/cpan-api/wiki/Wishlist) - things that probably need doing
 
+# Git workflow
+
+We try to keep a clean git history, so if it all possible, please rebase to get
+the latest changes from master _before_ submitting a pull request.
+
+    git pull --rebase origin master
+
+If you are comfortable rebasing, it is also helpful to squash or delete commits
+which are no longer relevant to your branch before submitting your work.  For
+example, to rework your last 15 commits.
+
+    git rebase -i HEAD~15
+
+Just be careful to rebase only commits which have not already been merged into master.
+
+# Coding conventions
+
+Please try to follow the conventions already been used in the code base.  This
+will generally be the right thing to do.  Our standards are improving, so even
+if you do follow what you see, we may ask you to make some changes, but that is
+a good thing.  We are trying to keep things tidy.
+
+In general, the concepts discussed in "Perl Best Practices" are a good starting
+point.  Use autodie where possible and MetaCPAN::Web::Types when creating new
+Moose attributes.  Many of the other standards will be enforced by Perl::Critic.
+
+Take pains to use variable names which are easy to understand and to write
+readable code.  We value readable code over concise code.  Use singular nouns
+for class names.  Use verbs for method names.
+
+Any time when a pull request includes a test, it makes it easier for us to
+review and accept, so please do test your changes whenever possible.  If your
+pull request includes visual changes, please include a before and after screen
+shot, so that we can better understand the problem you're trying to solve.
+
+Introducing new dependencies is fine, if they solve a specific problem which
+current dependencies cannot address.  If we prefer a different module to be used,
+we'll let you know.
+
+If a pull request contains any controversial changes, we'll likely wait for some
+feedback from several developers before a merge.  If you think your changes may
+be controversial, feel free to discuss them in a Github issue before starting to
+write any code.
+
+We use Travis to test all code changes.  After submitting your pull request,
+remember to check back to see whether Travis has come back with any test
+failures.  We do get some false negatives.  If your pull request failed for
+reasons unrelated to your changes, we may still be able to merge your work.
+
 # Additional Resources
 
   * [\#metacpan](http://widget01.mibbit.com/?autoConnect=true&server=irc.perl.org&channel=%23metacpan&nick=) IRC channel on irc.perl.org
@@ -55,4 +104,3 @@ explaining why it needs re-opening and we'll look at it again.
  * Issues will be closed and moved to [Wishlist](https://github.com/CPAN-API/cpan-api/wiki/Wishlist) if they are not actual bugs
  * Issues we think we have addressed will be closed
  * Issues we are not going to take any further action on without more information will be closed
-