Repetitive Process

  1. Find an open need1
  2. Google & search GitHub to find prior art, if any.
    • Someone got 80% of the way there: write a pull request instead
    • Read through their source and there’s room for something else: do it
    • If it’s going to be a module, check npmjs.org for namespace conflicts: npm search modulename
  3. cd src
  4. mkdir project. Do not name your project yet.2
  5. cp ~/bin/index.html .
  6. v .
  7. Split the window in iTerm 2 and run serve in the other pane to preview
  8. Write enough of index.js to get things running
  9. If there are dependencies:
    • npm init leads you through creating a package.json file for npm
    • npm install --save dependency both installs a dependency and saves it in your package.json file.
    • If this is a browser-based project with dependencies, write a Makefile that runs browserify (example) and then run watch make in a tab in iTerm. The watch command will run it every 2 seconds and make will noop unless there are changes
  10. git init .
  11. If the repository is something that lives on the web, git checkout -b gh-pages and only use the gh-pages branch for everything3
  12. Create a README. A good readme has:
    • A 2-4 sentence English description of what the thing can do for you and why you would want it. Note: not how it does what it does or, what it is, but what it does for you. Software is a thing you use.
    • An example that steps through requiring the thing, doing something useful with it, and integrating this with the outside world. Examples are not random examples of how you would use functions: they are examples of how things fit together.
    • API documentation for all public methods, which describes inputs, outputs, expectations, and behaviors.
    • A ‘See Also’ section if this project has open-source brothers and sisters, or took heavy inspiration from some other project or paper.
    • READMEs do not need to include the software license (this can be in LICENSE), nor the name of authors (this is in package.json and the commit history), nor TODOs (this is in your issue tracker or code). READMEs are about present code, not people, laws, or plans.
  13. Add files and a message for the first commit with vim-fugitive
  14. git create
    • Creates the repository tmcw/project with the hub utility
  15. npm publish to publish the first version of the module
  16. When you’ve gotten to fixing issues, create an issue for every problem, and create commits in vim-fugitive, using vim-rhubarb to reference and close those issues from commit messages.
  17. Once the thing works, read over everything, install it and test it. If it’s a library that isn’t totally self-explanatory don’t release it without releasing something that demonstrates why it is interesting, whether that’s another piece of software or just something in examples/. Do not fall into the trap of undemonstrated potential: connect the dots and prove worth.

  1. an open need: a finite need that people have. People can be just you, but it should not be just you just right now: the impact of technology is people × time.
  2. do not name your project yet: registering domain names for projects before they have code on the ground has cursed every single one. and if your project is code, you do not know what it will be yet: it could be one piece, a lot of parts, or just documentation and a blog post.
  3. use gh-pages for everything: you don't _need_ a master branch. If something else is default, people will clone that by default, automatically. `gh-pages` is just like `master`, except with perks: automatic, free web hosting.
  4. </ul>

Posted Aug 22, 2013 Tweet / Follow me on Twitter

Tom MacWright

I'm . I work on tools for creativity at Mapbox. This is where I write about technology and everything else.