block by roachhd b27871066a63cdab0e62


Your project should include the following:


Submodule the wiki into the notes/ directory

The notes/ a git submoduled version of the project’s wiki. If the sections outlined in the README README become lengthy, separate them into files named as follows:


Rakefile for simple scripts

Guardfile automates iterative development

Procfile shows how to launch support daemons and longrunning apps

Supply a procfile that will start

Include the following in the header block:

# Procfile -- supporting daemons
# * Ensure you've done a `bundle install`
# * run `foreman start [process name]`

List each daemon, with no path (if it’s typically a system-wide dependency) or a path relative to the top of the repo. Here’s an example goliath Procfile:

listener:   ./app/listener.rb -sv -p 9000 -c $PWD/config/app.rb
mongod:     mongod

Gemfile is a manifest for ruby gem dependencies

Gemfiles for appllications should be precise about their direct dependencies. Gemfiles and gemspecs for libraries should not be strict with version dependencies. For example:

gem 'gorillib',      "~> 0.1.8"
group :development do
  gem 'yard',        ">= 0.7"
  gem 'pry'

As written, any version of pry will work – it’s included in the Gemfile so that we debug with binding.pry, but there are no code dependencies in the library. The documentation uses some modern features of yard, so we ask for a version newer than 0.7; but if other libraries specify some future "~> 1.0" version we would rather break our docs than your app.

A library with a strict Gemfile leads to conflicts that are nearly impossible to work around in current versions of bundler. A library with a too-generous Gemfile might break on an upgrade of some dependency, but it’s straightforward to correct by pinning a version in my app.

If the repo is a standalone-deployable application (web app, wukong job) you should include the Gemfile.lock file: it says “I don’t care what’s on the machine, use this precise gemset”. If the repo is not a standalone-deployable application (most things) you should not include the Gemfile.lock file. Add it to your .gitignore.

Pesky config files: .yardopts, .rspec, {reponame}.gemspec (yes), .rvmrc (hell no)

You should not version the following:

Tests and examples

specs holds RSpec test scripts

examples/ holds example apps or scripts

Your best be is to include

You should write tests for the examples, though they’re typically as simple as ‘its ran successfully and its output was what I expected’.

data/ holds example data (keep it small and interesting)

Place data files in data/ with helpful, descriptive names. Use something fun and domain-interesting. For structured data, use YAML if possible, JSON if necessary (YAML is more readable). Do not use any of the fancy features of YAML (anchors, references, baked-in types). For tabular data, use the TSV (tab-separated values) format. TSV files must not use any quoting or escaping; unless it’s as simple as ‘one line per record, split on tabs for fields’ fall back to JSON. If at all reasonable, run TSV files through wukong’s wulign script – it pads with spaces to make the data readable.

Don’t put anything larger than a few dozen KB in the directory – if a larger payload is necessary, make a {reponame}-data repo and submodule it into the data directory.

The subdirectory data/expected_output should Have your examples output to tmp/actual_output; its contents should exactly mirror that of the expected output directory (letting me diff -ruw data/expected_output tmp/actual_output to detect differences). You should .gitignore the contents of the actual_output directory, but .gitkeep the presence of that directory.