Stitch Fix Open Source

Open Source software is a huge part of our success. These projects are our small contribution back.

Stitch Fix Open Source

Open Source Repository Guidelines

Describes the bare-minimum needed in any open-source GitHub repository.

General

  • A decent README.md, based on this outline

  • A CONTRIBUTING.md, based on this template

  • A CODE_OF_CONDUCT.md based on this template

  • Configuration for continuous integration in Travis CI.

    Configure .travis.yml such that it triggers builds on all platforms in use by Stitch Fix, all reasonable platforms in use by the community and whatever the bleeding edge is. For example, Ruby libraries should be built on the two latest support versions of Ruby as well as ruby-head.

  • When releasing versions, make use of the GitHub Releases feature:

    1. Create a tag named v1.2.3 following Semantic Versioning.
    2. This will create a release in GitHub. Edit that release
    3. Itemize out all changes since the last release. These should all reference pull requests
    4. If someone outside Stitch Fix contributed to the PR, thank them explicitly using GitHub @-mentions.

    A good example is immutable-struct.

  • Prefer the MIT license, and include it in LICENSE.txt

  • Try to make your initial commit message something more fun than “Initial Commit” :)

Ruby

  • Gems should be laid out in a standard fashion.

    • The gem name should use underscores as word separators.
    • All code goes in lib/gem_name, for example lib/merch_calendar
    • The mail file in lib/gem_name.rb should establish a namespace module and require all the other files. It should be sufficient to require just this file in order to use the gem.

      module MerchCalendar
      end
      
      require 'merch_calendar/version'
      require 'merch_calendar/util'
      # ...
    • There should be a file named lib/gem_name/version.rb that contains the gem's version inside its namespace in the public constant VERSION

      module MerchCalendar
        VERSION = "1.1.3"
      end
    • Do not assume Rails. Explicitly require dependencies in each file, and require only what you need.
    • Put all dependencies in the Gemspec. Your Gemfile should generally be pretty empty.
    • Prefer RSpec and put all tests in spec/.
    • Your Rakefile should be able to run tests and release the gem. This is a good start:

      require 'rubygems/package_task'
      require 'rspec/core/rake_task'
      require "bundler/gem_tasks"
      
      RSpec::Core::RakeTask.new
      
      task default: :spec
      
  • Gemspecs should be consistent

    • Start with what bundle gem gives you for a Gemspec.
    • spec.authors should have “Stitch Fix Engineering” as the first author.
    • For each Stitch Fix employee that has contributed, list them in spec.authors after “Stitch Fix Engineering”.
    • For significant contributes from non-Stitch Fix employees, list them as well (ask permission first).
    • spec.email should contain eng@stitchfix.com, followed by the primary GitHub emails of the contributors in spec.authors.
    • spec.description and spec.summary should be identical and match the description in the GitHub repo.
    • spec.license should match the license.
    • spec.homepage should be the GitHub page.
    • Add runtime dependencies judiciously. When you must keep the version as loose as possible.
    • Keep development dependencies' version requirements as loose as possible.
  • Write and publish documentation.

    Use RDoc for all public members and configure the gem on RDoc.info.

  • Release as the shared user

    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.