Detailed expectations for those contributing to this repository. A documented branching strategy is recommended. Trunk based development as default.
This project uses a git-flow based development branching strategy.
Trunk-based Development vs. Git Flow
Branch naming must be consistent and must be in kebab-case. The following pattern is recommended -
- feature-[Issue Number]/* - Feature additions
- bugfix-[Issue Number]/* - Bug fixes
- chore-[Issue Number]/* - Chore tasks
- doc-[Issue Number]/* - Documentation tasks
- release/[release-version] - Release versioning
For example,
- feature-27/setup-postgresql
- release/1.0
Consistent, verbose commits reduce the need for additional documentation. May be used for generating changelogs. Detailed instructions must be included either through a documented specification or custom documentation.
This project uses the conventional commit specification for commits.
https://github.com/talos-systems/conform
Consistent tense in commit messages.
In keeping with the standard output of git itself, all commit subject lines must be written using the imperative:
Your commit subject line must be able to complete the sentence
If applied, this commit will ...
If it doesn't, it's non-conformant. The body may use any style you want.
Especially if the diff is rather large or extremely clustered, you can save all fellow developers some time by explaining why you did what.
When possible the addition of screenshots, recorded gifs or other visual media is recommended.
| First Word | Meaning |
|---|---|
| Add | Create a capability e.g. feature, test, dependency. |
| Cut | Remove a capability e.g. feature, test, dependency. |
| Fix | Fix an issue e.g. bug, typo, accident, misstatement. |
| Bump | Increase the version of something e.g. dependency. |
| Make | Change the build process, or tooling, or infra. |
| Start | Begin doing something; e.g. create a feature flag. |
| Stop | End doing something; e.g. remove a feature flag. |
| Refactor | A code change that MUST be just a refactoring. |
| Reformat | Refactor of formatting, e.g. omit whitespace. |
| Optimize | Refactor of performance, e.g. speed up code. |
| Document | Refactor of documentation, e.g. help files. |
Documentation must be treated as an integral aspect of development. This section describes expectations for documentation rigor and placement.
In cases where the impact of a change is such that it is affects a fundamental component of the system, additional documentation is needed above what is presented in commit messages. This is by discretion, but it is advised to err on the side of more documentation than less.
In these cases, documentation should be added as markdown files within the project directory.
Expectations for conducting code reviews, the merger of code and subesquent tasks
Pull requests require a minimum of one reviewer to accept changes prior to merge. It is the responsibility of the person submitting the pull request to schedule a code review.
Google Engineering - Code Review Developer Guide
Deployment steps from the perspective of an engineer required to deploy to all of the available evironments.
Once a pull request is merged the change will be automatically deployed to the appropriate environment.
Description of how tasks are tracked through project management software and expectations of different roles.
- All acceptance criteria have been met
- Implementation has been code reviewed
- All automated tests pass (e.g: Unit, end-to-end testing)
- All manual tests pass (e.g: Functional, user interface testing)
- Necessary documentation is reviewed
- Implementation is deployed to the appropriate environment
The following technologies are required for development
- Node.js
- Java
- Micronaut
- Podman or Docker
- Gradle
For instructions on setting up your development environment, see Setting up your environment.