Now that we have more people working on AcousticBrainz I’ve been thinking about how we can add some structure to the way we plan and develop new features. I’m putting down some ideas here, and hope to get feedback from the community about what we think will work well or not.
Bugs and new feature tickets
We use MetaBrainz Jira for all tickets, in the AcousticBrainz component.
Feature tickets should be fully described. This means that the layout of any websites should be fully explained, either in text, sketches, or mockups. All items/links on the page should have their behaviour described (e.g. “Table columns should be sortable, with the default being descending date”, or “Clicking ‘evaluate’ takes you to a page showing options for evaluation, which are x, y, z” (and then a description of how the next page works))
Implementation details are not as important as behaviour, although if there are some open questions they should also be discussed on the ticket.
Development should only be started once features are agreed on in the jira ticket.
All development must happen on a feature branch. Even if you create a fork and plan to make a pull request, development in your fork must be on a branch and not
We use github pull requests for code review. When creating the PR, you should always include a link to the Jira ticket in the message. On Jira, Resolve the ticket (this puts it into the PR state).
Every change should be OKd by at least one other person. For emergency bug fixes, they should have a PR opened even if the change was previously deployed.
PR discussion should be limited to style and bugs. New functionality that discovered to be needed should make discussion move back to the jira ticket.
I have a few questions which I’m not sure about.
- Should we have a ticket for every piece of work that we want to work on? Sometimes we find a small bug or think of a new feature that we want to add, and I currently just add it. The first notice that I was doing it comes at the PR stage. Should we require public outlines of all new components?
- Work in progress code reviews can be useful to see how a task is progressing and catch problems early, but they might move implementation discussion from jira to the PR. Is this OK?
- How strict should be be on commit messages? Should all commits for a ticket include the ticket number, or should we put this in the branch name and always use merge commits?
Please let me know what you think, or if there are any unanswered questions you have!