Guidelines for configuring a project with the best standards of the internet.
Define a standard for our projects to facilitate their identification, comprehension and execution of it.
In this section we present an overview of the components expected in an architecture that follows the guidelines standard.
Include standardized templates for:
- Pull Request
- pull_request_template.md
- Issues
- Bug Report
- bug_report.md
- bug_report.yml
- Config
- config.yml
- Documentation Request
- documentation_request.md
- documentation_request.yml
- Feature Request
- feature_request.md
- feature_request.yml
- Bug Report
To view examples of these files click in the links bellow:
- pull_request_template.md
- bug_report.md
- bug_report.yml
- config.yml
- documentation_request.md
- documentation_request.yml
- feature_request.md
- feature_request.yml
A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.
Workflow suggestions:
- Lint
- A linter or lint refers to tools that analyze source code for programming errors, bugs, stylistic errors, and suspicious builds.
- Unit Test
- A unit test exercises the smallest piece of testable software in the application to determine whether it behaves as expected.
- Component Test
- A component test limits the scope of the exercised software to a portion of the system under test, manipulating the system through internal code interfaces and using test doubles to isolate the code under test from other components. .
- Sonar
- Code analysis tool to check code quality, duplicate code, vulnerabilities and bugs.
- Versioning
- Perform project versioning following the SemVer standard;
- Guidelines
- Validates whether the project is following the guidelines definitions;
To view examples of these files click in the links bellow:
The project must have some files that help the user to understand the project, be able to install and run it, in addition to being able to obtain other information about it, using the respective files as a guide for the project evolution process.
List of the files:
- README.md
- You should add a README file to your repository to let others know why your project is useful, what they can do with the project, and how they can use it
- CHANGELOG.md
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- LICENSE.md
- For your repository to truly be open source, you'll need to license it so that others are free to use, change, and distribute the software.
To view examples of these files click in the links bellow:
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: GITHUB-DOCUMENTATION.md
The settings of code quality validation can be used by SonarQube or SonarCloud.
The sonar-project.properties file should contain the following settings:
- sonar.projectKey
- Project key in
SonarCloudplatform or project name;
- Project key in
- sonar.organization
- Company name or code registered on
SonarCloud;
- Company name or code registered on
- sonar.source
- Normally, a period (.) is used to refer to the root folder.
- sonar.exclusions
- Folders that do not have code created by developers or folders with files that are not relevant for analysis, e.g. configuration files, docker files, node modules.
- sonar.tests
- Folder containing all tests scripts;
- sonar.tests.inclusions
- Pattern to identify test files;
- sonar.{linguagem} .coverage.reportPaths
- Location of project coverage reports;
- Clover pattern;
- sonar.junit.reportsPath
- Location of project coverage reports;
- JUnit patter;
To view examples of these files click in the links bellow:
Files for dynamic API configuration.
A documentar
A documentar
A documentar
To view examples of these files click in the links bellow:
- openapi.yml
- UI
- Routes
- Schemas
The material that can be used to generate the inline documentation can be found here: https://swagger.io/specification/;
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: SWAGGER-DOCUMENTATION.md
When the project is an API, it is desirable that it implements the definitions of the RESTful standard. Even better if you can apply HATEOS concepts.
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: RESTFUL-HATEOS-DOCUMENTATION.md
- Designing-a-Beautiful-REST%2BJSON-API.pdf
- HTTP Methods for RESTful Services
- RESTful Web Services Resources
- REST-API-Design-Filtering-Sorting-and-Pagination
- HTTP Status Dogs
Configuration of docker files for the project.
Docker files must be in the docker folder, being organized by context, examples:
- docker/
- php/
- Dockerfile
- entrypoint.sh
- nginx/
- logs/*
- Dockerfile
- app.conf
- nginx.conf
- python/
- Dockerfile
- entrypoint.sh
- php/
File with the references of folders and files that should be ignored by docker during copying of the project folder's contents.
File with settings for managing containers in the development environment.
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: DOCKER-DOCUMENTATION.md
Quando o projeto for uma API, é requerido que o mesmo implemente um endpoint de healthcheck, é recomendado que
o projeto aplique o padrão definido da documentação da guideline, para que o mesmo seja um endpoint inteligente.
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: HEALTHCHECK-DOCUMENTATION.md
- Microsoft - Monitoramento de integridade
- Microsoft - Exemplo com ASP.NET Core
- Testfully - Artigo Health Check
Description of the folder structure and concepts.
- Tests that use mocks to avoid real connections to external components;
- Tests focused on functionality and not on the data itself;
- Tests to run in CI pipelines;
- The duration of these tests should be a maximum of 1s per file, ideally running in milliseconds;
- Tests that should not run fixtures or feature changes to avoid problems;
- Tests focused on the integration of external components with the application in question;
- Tests to run in CD pipelines;
- The duration of these will depend on the scenarios developed, however, it is recommended to create objective tests so that the pipeline does not take too long;
- Base tests for the TDD process;
- Tests focused on the behavior, scenarios and data of the project process;
- Tests to be executed locally in a docker suite that will provide local access to resources such as databases and the like;
- The duration of these will depend on the scenarios developed, but the idea of these tests is to explore several possible scenarios;
Below we have a link with more detailed information on this approach.
Para mais detalhes acesse: TEST-DOCUMENTATION.md
WIP
WIP
WIP
WIP
WIP
WIP
WIP
WIP
Specific settings for the git project.
File with the references of folders and files that should be ignored by git during development from the project.
WIP