Inside Gratipay

This is Gratipay's internal company portal. First time here? Welcome! Start at the top. :-)

Develop Software

We use Git hosted on GitHub to coordinate our software development. If you're not familiar with Git or GitHub, we'd love to teach you! :-) Start by reading some of GitHub's guides. Then sign up for a GitHub account, and introduce yourself in a new onboarding issue. You're likely to be invited to join our GitHub team pretty early in the onboarding process.

All the documentation related to development can be found at gratipay.readthedocs.io.

Repos

We have a number of repos; the main ones for our user-facing software are:

Guidelines

  1. Make pull requests from topic branches in the relevant repo, rather than from personal forks (though if you haven't onboarded yet then by all means make PRs from a fork).

  2. The net change for a pull request (PR) shouldn't be more than about 400 lines (additions + deletions). Split your work up! Small batch sizes are easier to process. :-)

  3. Every PR should result in deployable software.

  4. Every pull request belongs to the whole team. Don't be surprised when someone else pushes commits to a PR that you started! :)

  5. Every PR should be explicitly approved by at least two people, you and at least one other, before it's merged.

  6. It's best for someone besides the last committer to merge.

  7. Basically anyone who wants to care about a given PR is responsible to get in there and be part of the conversation and development. We need at least two people, but if a third sticks their head in then the PR now has three people who need to agree by consensus before someone besides the last committer merges.

  8. True self-merging, with no review whatsoever, should be rare and documented—except ...

  9. You can self-merge PRs that only change documentation, though you should still use PRs rather than committing directly to master. More docs!

  10. Write documentation! Everybody needs it, and it helps make our software better software. It's also a part of our build process: if the docs don't build, the build is broken.

  11. When you have a PR ready, apply the "Review" label (every repo is supposed to have this label), and ping a couple specific people to ask for a review and merge, either in a comment or using GitHub's formal review workflow. If no-one is reviewing your PRs, try reviewing some others to create some social pressure! :-)

  12. Unfortunately, GitHub's review workflow encourages a rather individualistic and bureaucratic relation, where a PR is owned by a single person, who has to seek formal approval from others—but that's not how we operate. Therefore, think of review requests as invitations and not requirements.

Rebase or Merge?

We're somewhere in the middle. We often rebase and force-push PR branches, especially when constructing a long chain of PRs (see Guideline 1). We'll often squash PR branches early in their development, and then end up with additional commits in response to code review. We always rebase PRs when syncing with master (often noting the previous head commit in a comment), but we merge back to master without squashing.

Table of Contents