[Proposal] Development workflow

Busy gets more and more external and internal contributions. We should make sure we are capable of scaling from tens to hundreds of contributions weekly. Because of that, I would like to propose some changes to our development workflow:

1. Making sure our repository stays clean. Our repository is already at 4600 commits and it makes it would be hard to revert to some point in time if needed. We can’t (shouldn’t) update old history, but we can make an effort to keep our future git history better. To do this we should enforce few rules:
   1. Don’t EVER push to dev or new-design without pull request. It doesn’t matter if it’s a just simple fix or anything else. No code should go to the repository without review (see below).
   2. Don’t use busyorg/busy for your local work. Our repository should only have branches that are relevant to our release cycle. We might want to have dev and new-design branches and additional branches for bigger pieces of work that could have multiple contributors working on them. It would be hard for external contributor to work on wallet page alone, but if we would create a branch wallet-page and allow multiple contributors to create PRs to that branch with small chunks of code (like fetching data, styles, displaying data, adding tooltips, adding minor functionality) it would make it easier for them to contribute. After we agree that wallet-page is finished we can approve and merge PR from wallet-page to new-design. Any work that won’t require contributions from more than yourself (so usually some small changes) should take place on a fork. If there is branch inside busy repository you should never push to it directly, use pull requests instead.
   3. Use merge --squash or rebase if merging more commits than desired. If it makes sense to squash commit into one, do it. If you feel that one commit is not enough, rebase your work into multiple commits that have clear description and purpose. If you have a clean commits with a proper description, you can merge it just fine (but I don’t think we should ever have bigger merges than 2-3 commits and it should be reserved only for big changes).
   4. Limit number of people that can merge pull requests. It’s better to wait some time to let other developers get familiar with changes and share their thoughts on those changes than merging improperly or with low quality, buggy or dangerous code.
   5. Be strict about what goes into our repository. Introducing bad code is easier than turning bad code into good code. If we let bad code in, this will require additional work to get it rewritten properly. Don’t do this: https://twitter.com/iamdevloper/status/397664295875805184. If you are not 100% sure about something ask others for help.
2. Improve the quality of issues and pull requests.
   1. Use good explanation for what is going on. Not all Trello cards have been migrated to GitHub issues yet, so don’t reference them in PRs or issues, because they are not public. Explain what are you doing so even people that don’t have access to Trello can understand what is the thing that is being worked on. This will prevent situations when two people are working on the same thing simultaneously.
   2. We should make sure that we don’t have multiple people working on exactly the same thing at the same time. We use issues so we can discuss who will work on some bug or feature. If someone wants to take on this issue, they should be assigned to that issue.
   3. Use descriptive names for commits as well as issues and pull requests. Pull request title should focus on changes, not say what kind of bug it does fix (so Don’t show already followed users in recommendations instead of followed user appears among recs after reloading the page - the former makes it clear what has been changed, the latter sounds like it’s adding new bug).

[bonustrack]

I think we should have the branch master and stable it’s less confusing. stable would be versioned and used for production. While master is used for development. We can setup the domain staging.busy.org with master branch to test every new version before it get released. It would look like this: Got this schema from these branching guides that we can follow: https://gist.github.com/digitaljhelms/4287848 https://datasift.github.io/gitflow/IntroducingGitFlow.html

[Sekhmet]

1. They are protected.
2. We don’t have specific release schedule, so gitflow isn’t so relevant to us. I’d recommend using just two different types of branches:
   • target - like dev and new-design that are used for production deployment
   • progress - like voting-slider or wallet-page that are used for tracking work for certain feature/fix. Other branches should be hosted on forks (https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)

Workflow

This is just proposal and should be discussed to make sure we can get the most out of it. We might want to start using some of those ideas already to make migration to this new workflow as smooth as possible.

Branches

I think we should have two kinds of branches:

1. target used for deployment. Ideally top-notch code that can go (and goes) to production. For now we have two of them dev (Busy 1) and new-design (Busy 2)
2. progress used for cooperation among contributors. If more than one person works on some feature, they should create PRs to their progress branch and after first code has been pushed to that branch we should create PR that will eventually merge from progress branch into target. This feature PR should be used for tracking progress and discussion related to this feature.

Core members shouldn’t use busyorg/busy for local work and use forks instead (https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow).

Issues

Should be used for discussing new features, ideas and bug reports, before starting work on anything. We should have a plan before writing code. Before anyone starts working on it, we should know how it’s supposed to work, look like and how we want to achieve this. If someone wants to work on this issue they should be assigned to that issue, so we would avoid having multiple people working on exactly same thing. It’s okay to have multiple people working together on same concept, but they should agree what their responsibilities are we should provide progress branch for them so they can cooperate. It’s highly recommended to give abstract opinions at stage of planning in issue. When work has started and PR has been created there should be only code-related discussion, ideally without any “we don’t need this” comments.

Pull requests

After planning phase person that has been assigned to relevant issue should create PR shortly after writing first code. This allows us to track progress, notice problems early and solve them faster. In case of small changes PRs might be created after work is done. Pull request should clearly reference issue that it concerns. (using fixes and closes keywords). It should include list of changes made (in terms of UX/bugs not code changes, unless it’s code related pull request). Pull requests are good place to have code related discussion. If there is anything that needs be discussed that is not related to code and implementation use proper issue for this. After work is done notify others and request review. Before merging:

• ideally wait for at least 2 approvals
• don’t merge anything seconds after approval. Wait couple hours and merge no one has anything against it.
• if there is review hanging without explicit approval wait for this person to review code, you can mention it in comment as a form of reminder
• ideally PRs should end up as one commit so use Squash and merge option. Use other option if you know what are you doing. Add commit description when squashing that explains what does that commit do.

Reviews and approvals

Take your time to review PR properly. If you don’t have time to review, ask somebody else to do this for you. Request changes when you think that this code shouldn’t land on target branch. Use comment when you don’t have strong opinion on some piece of code. Approve if you think that this code is worth merging into target branch. Make sure everything works properly - you can review new functionality using heroku deployments, ideally you should test it locally to see if it doesn’t cause any problems on your machine.

General information

Issues and pull requests titles should be clear and easy to understood even without reading description. If there are issues or pull requests with low quality titles update them. For branch names use kebab-case.