Hi!
We are Substance Lab. We craft awesome web software for picky customers.
This is our playbook. It describes how we work, and how we make our customers and their projects successful.
We have decided to open this with the world because we believe in sharing. If you like what you see and especially if you use any of the ideas described here, feel free to let us know.
We're a consultancy; doing client work is our primary focus.
We schedule projects on a daily basis so we can focus on one project each day, not having to context switch between multiple projects. If possible, we’ll schedule multiple, successive days for the same project.
We start each week with a team-wide status meeting where we take a look at the schedule for the week and everybody is kept up to date on new leads and sales and general announcements.
We’re geeks and we thrive on playing, experimenting and building. This means we work 4 days of the week on client work, while the last day (typically Friday) is for geek days.
If a week has less than five days due to personal time, vacations, holidays, sick leave, the geek day for that week is skipped.
Geek days should be used for stuff that is somewhat related to the business or to self improvement. This could be
- Contributing to an open source project (you can find contribution suggestions on Code Triage)
- Creating an open source project
- Writing a blog post
- Learning a new technology
- Optimizing a workflow
- Improving internal tools
- Preparing presentations for user groups or conferences
- Helping people on Stack Overflow, Exercism or elsewhere.
Every so often we'll use an investment day to build something, anything. The rule: It must be built and launched in a single day. Planning it beforehand is acceptable, though, and probably a good idea. We keep a list of Single Day Product Ideas where we hash out ideas.
The main branch is our main branch. It is always working and deployable so we can confidently base future work on it.
Don’t commit directly to main. Create a branch for whatever you’re doing, make your changes and commits on that branch.
When making changes make sure you run all the tests in the test suite, not just the ones you think you might have impacted.
The full test suite should be run on CI whenever changes are pushed to remote branches.
When your changes are ready to be reviewed, create a pull request for the branch. When your pull request is complete ask for reviews from the other members of your team by using GitHubs "Request review" feature or GitLabs "Assign approver".
See The Anatomy of a Good Commit for guidelines of how and why to create good commits.
- If you feel the need to put "and" in your commit message, the commit is probably too big.
- If you find it difficult describing what your commit does, it's probably too big.
- If you find it difficult describing the "why" of your changes, your commit might be too small.
Explaining what you did is nice, explaining why you did it is even nicer. It’s even more useful if you explain why you did it over other options.
See How to Write a Git Commit Message for an overview of how to write (and why) good commit messages. In summary:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
Grab the most important, ready story from the project management tool (GitHub, Waffle, whatever your project uses). Assign it to yourself and…
$ git checkout main
$ git pull
$ git checkout --branch ISSUE_NUMBER-ISSUE_DESCRIPTION
… make your changes and commit each change in small, atomic commits. When done …
$ git pull
$ git rebase —interactive main
$ git push --set-upstream origin
Create a pull request on GitHub.
$ git checkout main
$ git pull
$ git checkout --branch ISSUE_NUMBER-ISSUE_DESCRIPTION
... make your changes and commit each change in small, atomic commits. When done ...
$ git pull
$ git rebase main
$ git push --set-upstream origin
Create a pull request on GitHub.
All work and changes are pushed to a remote branch before leaving work every day. This way another developer can take over with minimal loss if you aren't at work the next day.
We generally follow GitHubs Ruby style guide.
A Rubocop configuration is available as part of our dotfiles project.
We generally write CSS using the Sass syntax. We strive to adhere to the guidelines from SMACSS.
A few guidelines:
- Colors are always 6-digit, lowercase hex (ie
#abcdef), unless we need the alpha channel, in case rgba is used. - Rules, selectors are placed in alphabetical order as much as possible.
- Place used mixins at the top to make it possible to overwrite their values.
We strive to include a set of scripts in all repositories that gives a uniform way of performing common development tasks across projects, frameworks, and languages.
script/deploy: Deploys the application to production (usually).script/run: Launches the application for local development.script/update: Ensures application dependencies are installed and upgraded, and that the application is otherwise in pristine order for development.
New customers are tracked on our Sales board in Trello.
- Leads - Someone contacts us.
- Contacted - Initial followup with a questionnaire.
- Meeting - We have a phone call or have them come into the office.
- Estimate
- Proposal sent
- Won/Lost
At the beginning of each year, when the results from the year prior are done, we donate 10% of the yearly result to a given charity. The charity is chosen each year by all of us based on suggestions and votes from all employees.
We believe in a healthy work/life balance and expect employees to take days off. We provide 5 weeks of paid time off every year.
Upcoming vacations should be registered in Salary at least 3 weeks in advance.