diff --git a/docs/dev-guide/api-doc-gen.md b/docs/dev-guide/api-doc-gen.md index 2fc9a8c..f145c82 100644 --- a/docs/dev-guide/api-doc-gen.md +++ b/docs/dev-guide/api-doc-gen.md @@ -9,7 +9,7 @@ - MKDocs has a great extension `mkdocstrings-python` for this purpose. - Example markdown page to automatically extract docs: -```markdown +```md # your_module.py ::: your_package.your_module.function1 diff --git a/docs/dev-guide/repo-management/git.md b/docs/dev-guide/repo-management/git.md index 97efef4..afea967 100644 --- a/docs/dev-guide/repo-management/git.md +++ b/docs/dev-guide/repo-management/git.md @@ -24,8 +24,8 @@ The primary branches, in order: - **Development**: the branch that fixes or features are continually merged. - **Staging**: where development branch fixes/features are grouped and tested together, with the intention to push to production once QA/QC passes. -- **Production**: where staging is stabilised and released at intervals as actual - versions of your tool/software. +- **Production**: where staging is stabilised and released at intervals as + actual versions of your tool/software. Additional supporting branches: diff --git a/docs/dev-practices.md b/docs/dev-practices.md new file mode 100644 index 0000000..c88b55f --- /dev/null +++ b/docs/dev-practices.md @@ -0,0 +1,156 @@ +# HOT's Development Practices + +This was last updated on 08/07/2024 and details our idealised +software development practices. + +## Open-Source Model + +- All code developed at HOT is open-source. + - We rely heavily on community feedback to steer our development. + - Contribution from **anyone** is welcome. +- We follow a git-flow, or fork-and-pr model: + - Developers should create a fork of the repo they wish to modify. + - Code is added to a branch inside _the fork_. + - A pull request (merge request or PR) is made against the development + branch of the original repository. +- Our code is generally licensed + [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) + unless otherwise specified. + +## Repo Management + +### Branches + +- Generally our repos will have three key branches: + - **dev**: the ongoing development to which PRs are made. + - **stage**: optional branch where new features pass quality control + stages prior to deployment to the main website. + - **main**: the code that is currently deployed to the main website. + +### Issues + +#### Issue Labels + +- Label issues where appropriate, for example as backend or frontend. +- Priorities can be assigned:. + - `priority:critical`: blocking current tasks or user workflow. + - `priority:high`: should be addressed as a priority. + - `priority:low`: backlog of tasks that will be addressed in time. +- Difficulty can be **estimated** (and may not be accurate): + + - `effort:low`: small task, likely a few hours. + - `effort:medium`: larger task, may take a day or two. + - `effort:high`: a broader scope task with unclear timeline. + + > Ideally there should not be many tasks with `effort:high`. + > If there are, consider breaking them down to smaller tasks. + +- The quality control status can be tracked: + - `qa:ready`: the issue has been fixed and is ready to test. + - `qa:fail`: the issue was not fixed as intended and requires additional + work from the developer. + - The `qa:xx` label can be removed when an issue is closed. + +#### Issue Assignment + +- Assign issues to the dev who will work on it. +- Issues can be assigned in advance if the devs is known. +- Devs can self-assign tasks. + +### PRs + +#### PR Drafts + +- Create a draft PR for works in progress. +- Push as early as possible to draft, especially if there is a chance you + may get sidetracked on other work (so another dev could feasibly pick + up where you left off). + +#### PR Assignment + +- Assign yourself if you are working on the issue. +- Assign another dev if you need to pass off the development to them. +- The re-assigned dev can then assign the task back to the original dev for + validation. + +#### PR Review + +- Any developer can review a PR, **as long as one dev reviews** prior to + merge. +- Assign devs for review - frontend can review backend and vice versa. +- Once review is complete and the PR is out of draft state, then any dev can + merge. + +### Milestones + +- Encapsulates a set of issues into a logical bigger task, with or without + an assigned deadline. +- Discussed in team meetings and decided on via priorities. +- Project Owner (PO) decides on priorities, tech lead decides on which tasks + are required to achieve that goal. +- Milestones are grouped into a release, which has a set deadline. + +### Releases + +- A release encompasses multiple milestones, plus additional bugfixes + and minor improvements. +- Releases are tracked on the roadmap and have an _approximate_ deadline. +- Ideally releases should be around once a month at minimum, to regularly + deliver incremental updates to the user (~agile project management). + +### Roadmaps + +#### Technical Roadmap + +- Higher level roadmap based on releases and milestones. +- Managed on the Git repo hosting service (e.g. Github), linked in the README. +- The roadmap should include: + - Milestones spanning the work start and end date. + - Releases labelled over the top, showing the anticipated next release date + and how it relates to the milestones. + +#### User Roadmap + +- 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. + +### Task Board + +- An optional stage to easier visualise developer time. +- Should be as automated as possible: + - Issues added to a project are added to the backlog. + - Issues assigned to a dev are moved to 'In Progress'. + - Issues labelled with `QA Ready` are moved to 'Review'. + - Issues completed should be moved to 'Complete'. +- Ideally we can keep track of which developer is working on + what task. +- This becomes especially important when we also have outside collaborators. + +### Discussions + +- To discuss more general topics in the public, so that anyone can contribute. +- Partly used to document the design decisions we have taken. +- Tag people specially for input, as it makes them more likely to add ideas. +- We can also use these for the staging server tests on each release cycle, + e.g. + +### Release Notes + +- No technical details, move those to a dropdown in markdown: + +```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 +
+``` + +- Higher level info on bugs fixed, new features added, things improved. +- Add screenshots throughout. diff --git a/mkdocs.yml b/mkdocs.yml index be99cf5..a7f37f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,4 +118,5 @@ nav: - Local Kubernetes: dev-guide/containers/kubernetes-local-kind.md - DevOps: - Reusable Workflows: https://hotosm.github.io/gh-workflows/ + - Our Development Practices: dev-practices.md - Code of Conduct: code-of-conduct.md