diff --git a/docs/dev-practices.md b/docs/dev-practices.md index 19d83f2..5c19d89 100644 --- a/docs/dev-practices.md +++ b/docs/dev-practices.md @@ -17,13 +17,14 @@ software development practices. [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) unless otherwise specified. - > Note: some tools still use BSD-2-Clause: - > - > - Tasking Manager - > - Export Tool - > - Open Aerial Map - > - > [More details here](./dev-guide/repo-management/licensing.md) +!!! note + + Some tools still use BSD-2-Clause: + - Tasking Manager + - Export Tool + - Open Aerial Map + + [More details here](./dev-guide/repo-management/licensing.md) ## Defining **What** We Build @@ -154,11 +155,13 @@ Management of tasks and code via Github. - Ideally the repo should always have a few low priority `good first issue` tags to help foster open source contribution / onboarding. -> Note that to attach labels to an issue, the Github user requires at least -> `triage` level permission for the repo. -> -> This can be tracked at a repo level with a `contributors` group, including -> those that have contributed regularly to include them in the development flow. +!!! note + + To attach labels to an issue, the Github user requires at least + `triage` level permission for the repo. + + This can be tracked at a repo level with a `contributors` group, including + those that have contributed regularly to include them in the development flow. ##### Issue Assignment @@ -196,8 +199,10 @@ code! - Once review is complete and the PR is out of draft state, then **any dev can merge**. -> Note that once a PR is merged, the merged should ensure that the -> `testing:ready` label is applied to the relevant issue, if required. +!!! note + + Once a PR is merged, the merged should ensure that the + `testing:ready` label is applied to the relevant issue, if required. ##### Linking Issues @@ -216,8 +221,10 @@ code! - Once closed, this will be reflected on the milestone percentage, roadmap progress, and task board complete tasks. -> Note the distinction here between the **technical code review** and the -> the review of the solution from a **user perspective** via testing. +!!! note + + Note the distinction here between the **technical code review** and the + the review of the solution from a **user perspective** via testing. ### Project Management @@ -260,18 +267,28 @@ Example (from FMTM): - Most users do not want to delve into Github roadmaps and issues. - A simpler user-centric roadmap can be written in simple Markdown table syntax. -- The key columns / categories in order: - - In Progress: what is being worked on right now. - - Next: what will be worked on in upcoming releases. - - Future: a concept envisioned, but not fully planned out. -- The content should be worded as user stories: - For example: `As a user I should be able to push the button, to allow me to -track my mapping progress more effectively`. +- The table is a chronological timeline, divided into three categories: + - ✅ for done tasks + - ⚙️ for ongoing tasks + - [no emoji] for upcoming tasks -Example user roadmap (from FMTM): +Example user roadmap (from Drone TM): ![user roadmap](./images/dev-practices/user-roadmap-example.png) +!!! note + + Previously we used to use a three-column table with categories: + - In Progress + - Next + - Future + + However after agreeing as a team, we decided to streamline the approach to + be less verbose, and to better show the ordering of priorities, as above. + + The user-story based wording was also partially replaced using emojis for + the context of each feature (for brevity when used in a README file / front page). + #### Task Board - An optional stage to easier visualise developer time. @@ -303,14 +320,14 @@ Example: Example: -```md -
- Technical Summary - * Add healthcare form category & minor fixes by @spwoodcock in https://github.com/hotosm/fmtm/pull/1555 - * Fix/requested page redirection by @NSUWAL123 in https://github.com/hotosm/fmtm/pull/1559 - * Test coverage for update project route by @azharcodeit in https://github.com/hotosm/fmtm/pull/1557 -
-``` + ```md +
+ Technical Summary + * Add healthcare form category & minor fixes by @spwoodcock in https://github.com/hotosm/fmtm/pull/1555 + * Fix/requested page redirection by @NSUWAL123 in https://github.com/hotosm/fmtm/pull/1559 + * Test coverage for update project route by @azharcodeit in https://github.com/hotosm/fmtm/pull/1557 +
+ ``` ![release notes dropdown](./images/dev-practices/release-notes-technical-dropdown.png) diff --git a/docs/images/dev-practices/user-roadmap-example.png b/docs/images/dev-practices/user-roadmap-example.png index a023572..9a07e44 100644 Binary files a/docs/images/dev-practices/user-roadmap-example.png and b/docs/images/dev-practices/user-roadmap-example.png differ