Merge pull request #112 from stitchfix/open-source-guidelines

guidelines for open-source repos

_layouts/default.html

@@ -26,6 +26,9 @@ <h1 class="mb1">Stitch Fix Open Source</h1>
           <li>
             <a href="code-of-conduct.html" class="uppercase small">Code of Conduct</a>
           </li>
+          <li>
+            <a href="repo-guidelines.html" class="uppercase small">Repository Guidelines</a>
+          </li>
         </ul>
       </nav>
     </header>

_sass/site/_decoration.scss

@@ -10,3 +10,4 @@
   overflow: hidden;
 }
 
+

repo-guidelines.html

@@ -0,0 +1,146 @@
+---
+layout: default
+---
+<article>
+  <div class="container contain-to-md">
+  <header>
+    <h1 class="mb1 mt2 h3">Open Source Repository Guidelines</h1>
+    <p class="thin">
+      Describes the bare-minimum needed in any open-source GitHub repository.
+    </p>
+  </header>
+    <section>
+      <h1 class="h4 mb1 mt2">General</h1>
+      <ul>
+        <li>
+          <p class="thick">
+            A decent <code>README.md</code>, based on <a href="/templates/README.txt">this outline</a>
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            A <code>CONTRIBUTING.md</code>, based on <a href="/templates/CONTRIBUTING.txt">this template</a>
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            A <code>CODE_OF_CODUCT.md</code> based on <a href="/templates/CODE_OF_CODUCT.txt">this template</a>
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            Configuration for continuous integration in <a href="http://travis-ci.org">Travis CI</a>.
+          </p>
+          <p>
+            Configure <code>.travis.yml</code> such that it triggers builds on all platforms in use by Stitch Fix, all <em>reasonable</em> platforms in use by the community and whatever the bleeding edge is.  For example, Ruby libraries should be built on Ruby 1.9.3 and above as well as <code>ruby-head</code>.
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            When releasing versions, make use of the GitHub Releases feature:
+          </p>
+          <ol class="ml2">
+            <li>Create a tag named <code>v1.2.3</code> following <a href="http://semver.org">Semantic Versioning</a>.</li>
+            <li>This will create a release in GitHub.  Edit that release</li>
+            <li>Itemize out <em>all</em> changes since the last release.  These should <em>all</em> reference pull requests</li>
+            <li>If someone outside Stitch Fix contributed to the PR, thank them explicitly using GitHub <code>@-</code>mentions.</li>
+          </ol>
+          <p>
+            A good example is <a href="https://github.com/stitchfix/immutable-struct/releases">immutable-struct</a>.
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            Prefer the <a href="https://opensource.org/licenses/MIT">MIT</a> license, and include it in <code>LICENSE.txt</code>
+          </p>
+        </li>
+        <li>
+          <p class="thick">
+            Try to make your initial commit message something more fun than “Initial Commit” :)
+          </p>
+        </li>
+      </ul>
+    </section>
+    <section>
+      <h1 class="h4 mb1 mt2">Ruby</h1>
+      <ul>
+        <li>
+          <p class="thick">Gems should be laid out in a standard fashion.</p>
+          <ul class="list-condensed">
+            <li>The gem name should use underscores as word separators.</li>
+            <li>All code goes in <code>lib/gem_name</code>, for example <code>lib/merch_calendar</code></li>
+            <li><p>
+                The mail file in <code>lib/gem_name.rb</code> should establish a namespace module and <code>require</code> all the other files. It should be sufficient to require just this file in order to use the gem.</p>
+          <pre class="bordered border-xs border-gray p1 bg-white round-md">
+module MerchCalendar
+end
+
+require 'merch_calendar/version'
+require 'merch_calendar/util'
+# ...</pre>
+            </li>
+            <li>
+              <p>
+                There should be a file named <code>lib/gem_name/version.rb</code> that contains the gem's version inside its namespace in the public constant <code>VERSION</code>
+              </p>
+              <pre class="bordered border-xs border-gray p1 bg-white round-md">
+module MerchCalendar
+  VERSION = "1.1.3"
+end</pre>
+            </li>
+            <li>
+              Do not assume Rails.  Explicitly <code>require</code> dependencies in each file, and require <strong>only</strong> what you need.
+            </li>
+            <li>
+              Put all dependencies in the Gemspec.  Your <code>Gemfile</code> should generally be pretty empty.
+            </li>
+            <li>
+              Prefer RSpec and put all tests in <code>spec/</code>.
+            </li>
+            <li>
+              <p>
+                Your <code>Rakefile</code> should be able to run tests and release the gem.  This is a good start:
+              </p>
+<pre class="bordered border-xs border-gray p1 bg-white round-md">
+require 'rubygems/package_task'
+require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+</pre>
+            </li>
+          </ul>
+        </li>
+        <li>
+          <p class="thick">Gemspecs should be consistent</p>
+          <ul class="list-condensed">
+            <li>Start with what <code>bundle gem</code> gives you for a Gemspec.</li>
+            <li><code>spec.authors</code> should have “Stitch Fix Engineering” as the first author.</li>
+            <li>For each Stitch Fix employee that has contributed, list them in <code>spec.authors</code> after “Stitch Fix Engineering”.</li>
+            <li>For <em>significant</em> contributes from non-Stitch Fix employees, list them as well (ask permission first).</li>
+            <li><code>spec.email</code> should contain <code>[email protected]</code>, followed by the <em>primary GitHub emails</em> of the contributors in <code>spec.authors</code>.</li>
+            <li><code>spec.description</code> and <code>spec.summary</code> should be identical and match the description in the GitHub repo.</li>
+            <li><code>spec.license</code> should match the license.</li>
+            <li><code>spec.homepage</code> should be the GitHub page.</li>
+            <li>Add runtime dependencies judiciously.  When you <em>must</em> keep the version as loose as possible.</li>
+            <li>Keep development dependencies' version requirements as loose as possible.</li>
+          </ul>
+        </li>
+          <li>
+            <p class="thick">Write and publish documentation.</p>
+            <p>
+              Use RDoc for all public members and configure the gem on <a href="http://rdoc.info">RDoc.info</a>.
+            </p>
+          </li>
+          <li>
+            <p class="thick">Release as the shared user</p>
+            <p>
+              Do not release gems as yourself.  Release them as the Stitch Fix RubyGems owner.  See our internal document “Pushing Release of Open Source Gems” for the specifics.
+            </p>
+          </li>
+        </ul>
+    </section>
+  </div>
+</article>

templates/CODE_OF_CONDUCT.txt

@@ -0,0 +1,6 @@
+# Code of Conduct
+
+We are committed to keeping our community open and inclusive.
+
+**Our Code of Conduct can be found here**:
+http://opensource.stitchfix.com/code-of-conduct.html

templates/CONTRIBUTING.txt

@@ -0,0 +1,18 @@
+# Contributing
+Thanks for using and improving *YOURGEM*! If you'd like to help out, check out [the project's issues list](https://github.com/stitchfix/YOURGEM/issues) for ideas on what could be improved.  If there's an idea you'd like to propose, or a design change, feel free to file a new issue or send a pull request:
+
+1. [Fork][fork] the repo.
+1. [Create a topic branch.][branch]
+1. Write tests.
+1. Implement your feature or fix bug.
+1. Add, commit, and push your changes.
+1. [Submit a pull request.][pr]
+
+[fork]: https://help.github.com/articles/fork-a-repo/
+[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
+[pr]: https://help.github.com/articles/using-pull-requests/
+
+## General Guidelines
+
+* When in doubt, test it.  If you can't test it, re-think what you are doing.
+* Code formatting and internal application architecture should be consistent.

templates/README.txt

@@ -0,0 +1,70 @@
+# MyGem [![Build Status](https://travis-ci.org/stitchfix/YOURGEM.svg?branch=add_travis_yml)](https://travis-ci.org/stitchfix/YOURGEM)
+
+> It's a neat little gem that you're gunna *love*
+
+Have trouble being happy while you're coding Ruby? You've
+come to the right place. This gem makes it dirt easy.
+
+ - [Usage](#usage)
+   - [Installation](#installation)
+   - [Configuration](#configuration)
+   - [Use Cases](#use-case-1)
+ - [Documentation](#documentation)
+ - [Licence](#licence)
+ - [Contributing](#contributing)
+
+## Usage
+
+### Installation
+
+Add to your +Gemfile+:
+
+```
+gem 'my-gem'
+```
+
+Then install:
+
+```
+bundle install
+```
+
+If not using bundler, just use RubyGems: `gem install my-gem`
+
+### Configuration
+
+In `config/initializers/my-gem.rb`:
+
+```ruby
+MyGem.configure do |config|
+  config.my_config_param = ENV['MY_GEM_CONFIG_PARAM']
+end
+```
+
+### Use Case #1
+
+Most people will just...
+
+### Use Case #2
+
+But lots of others want to...
+
+## Documentation
+
+(links to other documentation)
+* RDoc
+* etc.
+
+## Licence
+
+*MyGem* is released under the [MIT License](http://www.opensource.org/licenses/MIT).
+
+## Contributing
+
+*MyGem* appreciates contributors!  Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+Everyone interacting in *MyGem*'s codebase, issue trackers, chat rooms, and mailing lists is expected to follow the *MyGem* [code of conduct](CODE_OF_CONDUCT.md).
+
+---
+
+Provided with :heart: by your friends at [Stitch Fix Engineering](http://multithreaded.stitchfix.com/)