This document contains the development and contribution guidelines. This guide intends to achieve consistency across the organization's projects.
It's recommended to read the User's guide and the Developer's guide for each repository before start contributing to the project.
The guidelines for specific languages and technologies are in Specific guidelines.
All the repository information (eg. tags, labels, description), code, commit messages and technical docs inside the repository must be written in English.
All external documents, pull requests and issue discussions, final user documentation, and any resource that is not part of the repository may be written in the local language.
All of the repositories must implement automated code quality checks.
No merges to main branches must be made if the code doesn't comply with quality requirements.
Some examples of quality checks are:
- Testing / Coverage
- Formatting / Linting
- Documentation
- Complexity / Metrics
- Typing (if apply)
- Dependency management / Outdated versions
- Security / Vulnerabilities / Known bugs
- Hardcoded Secrets / Keys / Tokens
Most of these tool can be ran using pre-commit. Install pre-commit in your local installation before commit any code. Follow instructions about installation in pre-commit documentation.
If you found a problem, you must fix or delegate and create an issue with the details.
If a repository has tests, no broken tests must be allowed to merge to main branches.
You should write tests for all the code you write. Consider the code that is not tested, broken.
You should make the coverage reach 100%, with a lower bound of 50% including branches.
For any bug, a test must be written to check the existence and the fix.
Recommended tests:
- Unit tests
- Integration tests
- Acceptance tests
- Regression and requirements tests
Repositories may specify a default editor.
If a default editor is chosen, must be specified in the project's README.md file.
All configuration for the default editor may be under git dvcs in their respective folder (Eg. .vscode, .idea, etc).
If you use another editor, please don't commit configuration files, instead, update or create instructions for them under the docs folder in the respective repository. This is to avoid having a lot of different configurations for different IDEs.
Write descriptive commit messages, which is the legacy you leave to other developers. An example commit message is:
Title (imperative voice)
Long description, multiline.
- New feature 1
- Bug fix 1
Tasks/Issues resolved
Most of the content of the commit message is already in the Pull Request description, you can copy the content when merging.
Preferably use the Github flow branching model. The names of the branches are at the discretion of the team. Use issues and pull requests to discuss and code reviews.
Don't let the branches get old. Keep branches simple, Is better to merge small features than risk a big branch be abandoned for a long time.
Write descriptive commit messages, which is the legacy you leave to other developers.
You should keep dependencies outdated with at most 1 major version, 5 minor versions, and no outdated patch versions since the latest stable release.
Follow guidelines from OWASP when possible.
Never commit secrets. Use .env files both for configuring docker compose or the app settings. Be sure the .env file is ignored in .gitignore.
TODO:
TODO:
Here is a list of specific guidelines:
Nothing here is written in stone, but the important thing is that something must be written. If there are better solutions & practices, consider implementing them.
To change the content in this document just create a pull request.