contributing.md

Contributing Guide

Thank you for wanting to contribute, we're happy you're here! ✨

These guidelines build upon the dwyl contributing guidelines, which can be found at https://github.com/dwyl/contributing

This document adds to this process, detailing what we have found useful during the course of developing our own application and giving a broad overview of changes for people already familiar with dwyl's contributing process.

In time, the whole process will be rewritten for clarity now that our focus has moved away from working with clients.

The vast majority of the additions here sit in two key areas:

• The use of the Github Project as a kanban board (this is not yet in our main workflow guide)
• New labels specific to this repo

Github project

We have been trialling the use of Github Projects in order to aid team communication, adding an extra level of clarity on what the status of each issue is at any given time.

In determining our kanban board columns, we are using a pared down version of our large team workflow described in dwyl/contributing#109 (comment). We have trialled having a column for each of our 12 workflow steps in the past and hypothesise that some of the columns, whilst useful for large teams, will not be required by our current small one.

For now, we are starting with 5 very simple columns:

• To do
• In progress
• Awaiting review
• Please test
• Done

These aim to:

• Diverge as little as possible from the default Github Project kanban workflow to aid consistency and therefore create familiarity for people coming to this repo as their first interaction with @dwyl
• Reflect our basic workflow progression and wording of our labels

The intention is to add columns only as the need for them arises.
For example, when we begin testing with users, we may find we need to add a column for user testing.

See #238 for the ongoing discussion on which columns have been proposed, accepted or rejected and why.

Workflow Updates, including Labels & Github Project

Part 1: Describe your Question, Idea or User Story in an Issue

No changes are being made to this section aside from a much stronger emphasis on the need for acceptance criteria to be included in the issue before work begins in part 3 (more details below).

Part 2: Validate the Need or Issue Exists

This section is where the work is performed by those who have write access to the repo and is where the key changes to the workflow will take place.

➡️ Step 1: Confirm the Need in the New Story/Issue

The Product Owner (PO) will confirm the need, but if the issue is confirmed, the PO will also:

A) Confirm that there is a set of acceptance criteria listed in the issue

• Acceptance Criteria should be in the form of a checklist of items in the original post. This way it will appear in the issue list, giving an idea of how much of the acceptance criteria has been met when the issue is worked on

• If no acceptance criteria is present, the PO should either:

  • 🏷️ Add the needs-criteria label to the issue to signal that this still needs to be added before work can proceed; OR
  • Add acceptance criteria to the original post if they are intimately familiar with what is required

B) Confirm that there is a proposed User Interface (UI) for the issue

🏷️ Similar to needs-criteria, a needs-ui label should be applied to the issue if no UI has been proposed and until a UI is agreed.

Note: This does not have to be the final, unchangeable UI. Every UI is a starting point for testing with people using the app.

➡️ Step 2: Assign a Priority to the Issue

⚠️ 🏷️ A priority label should only be used for the issues expected to come up in the next 2 sprints or so.

We are testing whether this is able to prevent the notion that priority-4 and priority-5 labels are "where issues go to die".

📊 Once an issue has acceptance criteria, UI (where applicable) and a priority label, it should be be added to the To Do column of the Github Project where issues are kept in prioritised order.

The To Do column of the kanban board should only contain issues that are ready to be worked on.

Part 3: Do the Work!

🏷️ Our process for the application of labels throughout the development work will remain as per our contributing guidelines which will not be duplicated here.

📊 The issue should be moved through the columns of the Github project as follows:

• Once an issue has been time estimated and an 'in-progress' label 🏷️ applied, it should be moved to the In progress column
• Once the work has been completed and a PR opened for review with the 'awaiting-review' label 🏷️ applied to the issue, it can be moved to the Awaiting Review column
• Once the PR is reviewed and merged with the changes deployed and a 'please-test' label 🏷️ is applied to the issue, it should be moved to the Please Test column
• Once the PR has been tested by the relevant party (usually the PO or the person who opened the issue), the issue is closed, which automatically moves it to the Done column

Currently, the moving of closed issues to the Done column is the only automated action in this process, but this will change in future.