development-workflow.md

@@ -1,22 +1,65 @@
+## Tickets
+
+### Ticket lifecycle
+
+* Every ticket starts off in the backlog
+* Some tickets get added to the roadmap, a subset of the backlog that's organised into milestones
+* Some tickets in the current milestone are given high priority
+* High-priority tickets are eligible to be worked on
+* When you start working on a ticket, assign it to yourself and label it `In progress`
+* When you create a merge request, label the ticket `In code review`
+* When your branch is merged, close the ticket if necessary and label it `Fixed`
+
+### Parent and child tickets
+
+* If a ticket involves more than one person, or more than one week of work, divide it into child tickets
+* Mention the parent ticket in the child tickets
+* Close the parent ticket and label it `Fixed` when all the child tickets have been fixed
+
+### Priorities
+
+* No priority label: we haven't decided whether to work on this ticket
+* `Low priority`: the ticket will be worked on eventually but isn't on the roadmap
+* `Medium priority`: the ticket is on the roadmap
+* `High priority`: the ticket is on the roadmap and should be worked on immediately
+
+### Categories
+
+* Every ticket should be labelled `Bug`, `Feature`, `Feature request`, `Task`, `Document` or `UX design`
+  * `Bug`: a defect that affects the user, e.g. a potential crash
+  * `Feature`: a user-visible improvement
+  * `Feature request`: a feature someone has asked for -- we might or might not implement it, but either way the request should be recorded
+  * `Task`: work that isn't visible to the user, e.g. refactoring or research
+  * `Document`: work that produces a document rather than code
+  * `UX design`: work that produces a design rather than code
+* Every major feature involves UX design and coding -- create child tickets for the design and coding tasks, don't add the `UX design` label to every feature
+
+### Resolutions
+
+* Every closed ticket should be labelled `Fixed`, `Duplicate` or `Rejected`
+  * `Fixed`: the issue described by the ticket was addressed
+  * `Duplicate`: another ticket describes the same issue -- add a comment mentioning which ticket
+  * `Rejected`: the issue described by the ticket will not be addressed -- add a comment explaining why not
+
 ## Branches
 
 * Always work on a branch
 * Name your branch after the ticket you're working on, e.g. `55-key-manager-refactoring`
 * Push your branch at least once a day so everyone knows what you're working on -- that will help us to avoid conflicts
 
-#### When your branch is ready to merge:
+#### When your branch is ready to merge
 
 * Make sure **all** tests are passing
 * Check the [pre-review checklist](pre-review-checklist)
 * Rebase your branch if necessary to fix any merge conflicts, e.g. `git rebase -i master`
-* Use `git push -f` to overwrite the remote branch after rebasing
+* After rebasing, use `git push -f` to overwrite the remote branch
 * [Open a merge request](https://code.briarproject.org/akwizgran/briar/merge_requests/new)
 
 ## Code review
 
 * At least one other person must review your code before it's merged to master
 * You should address all the reviewer's comments before merging
-  * If an issue needs to be fixed before merging, push the fix to your branch and let the reviewer know
+  * If an issue needs to be fixed before merging, push the fix to your branch and notify the reviewer
   * If an issue is better dealt with after merging, create a ticket and reply with the ticket number
 * Once your branch has been merged you can delete the remote branch
 
@@ -24,11 +67,10 @@
 
 * Check out and run the code as well as reading it
 * Make sure you understand what the code is doing and why
-* Don't be afraid to ask questions
+* Ask plenty of questions -- the goal is not just to find bugs but to ensure that you and the developer have a shared understanding of the code
 
 ## Tests
 
-* Run the tests before putting a branch up for review
 * To run the tests in Android Studio:
   * Select `Run > Edit Configurations` from the menu
   * Click `+` and select `JUnit`
@@ -37,24 +79,9 @@
   * Set `VM options` to `-Djava.library.path=../briar-desktop/libs`
   * Set `Use classpath of module` to `briar-android`
   * Click `OK` to create the run configuration
-* Alternatively, to run the tests from the command line:
+* To run the tests from the command line:
   * `./gradlew test --continue`
 
-## Issues
-
-* When you start working on a ticket, assign it to yourself
-* Label your ticket '[in progress](https://code.briarproject.org/akwizgran/briar/issues?state=opened&label_name=In+progress)' while you're working on it, then '[in code review](https://code.briarproject.org/akwizgran/briar/issues?state=opened&label_name=In+code+review)' while it's being reviewed
-* When your branch is merged, label the ticket 'fixed' and close it, or include 'Closes #55' in your commit message to close the ticket automatically (you still need to update the label)
-* As a rule of thumb, if a ticket takes longer than a day, break it into smaller tickets (mention the parent in the description)
-
-* Every ticket should be labelled 'bug', 'feature', 'feature request', 'task', 'document' or 'ux design'
-  * Bugs are mistakes that affect the user, e.g. potential crashes
-  * Features are work items that directly affect the user
-  * Feature requests are features that someone has asked for -- we might or might not implement them, but either way they're worth documenting
-  * Tasks are work items that don't directly affect the user, e.g. refactoring or research
-  * Document tasks produce text rather than code
-  * UX design tasks produce designs rather than code
-
 ## Meetings
 
 * At the start of each week, let the team know what days you'll be working via the standup channel
@@ -66,8 +93,8 @@
 
 ## Dependencies
 
-* If you have a task that depends on an earlier task that's awaiting code review, base your new branch on the branch that's awaiting review
+* If you're working on a ticket that depends on an earlier ticket that's awaiting code review, base your new branch on the branch that's awaiting review
 * When the first branch is merged, rebase the second branch onto master
 * You can put the second branch up for review by selecting the first branch as the target, instead of master
 * Mention the dependency in the second merge request
-* Remember to update the target branch when the first branch is merged
+* Remember to update the target branch of the second merge request when the first branch is merged