From 1026d11ddf0351f8ed37ff33558773da0a43df51 Mon Sep 17 00:00:00 2001 From: Franco Liberali Date: Tue, 8 Aug 2023 10:04:24 +0200 Subject: [PATCH] move contributing docs to readthedocs --- .github/ISSUE_TEMPLATE/bug_report.md | 4 +- .github/ISSUE_TEMPLATE/discussion.md | 7 ++ .github/ISSUE_TEMPLATE/user_story.md | 2 +- CONTRIBUTING.md | 127 +-------------------------- README.md | 2 +- docs/contributing/contributing.md | 66 ++++++++++++++ docs/contributing/developing.md | 94 ++++++++++++++++++++ docs/contributing/maintaining.md | 17 ++++ docs/index.rst | 10 ++- 9 files changed, 200 insertions(+), 129 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/discussion.md create mode 100644 docs/contributing/contributing.md create mode 100644 docs/contributing/developing.md create mode 100644 docs/contributing/maintaining.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 9cc652d2..608172f0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Create a report to help us improve title: '' -labels: Bug +labels: bug --- ## Describe the bug @@ -31,6 +31,8 @@ If applicable, add screenshots to help explain your problem. Please complete the following information: - badaas version [X.X.X] or commit hash +- go version +- database vendor and version (in case of bugs related with badaas-orm) ## Additional context diff --git a/.github/ISSUE_TEMPLATE/discussion.md b/.github/ISSUE_TEMPLATE/discussion.md new file mode 100644 index 00000000..9835b3a0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/discussion.md @@ -0,0 +1,7 @@ +--- +name: Discussion +about: Start a discussion for BaDaaS +title: '' +labels: question +--- + \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/user_story.md b/.github/ISSUE_TEMPLATE/user_story.md index 1112fab2..f9a6617a 100644 --- a/.github/ISSUE_TEMPLATE/user_story.md +++ b/.github/ISSUE_TEMPLATE/user_story.md @@ -2,7 +2,7 @@ name: Feature request about: Suggest an idea for this project title: '' -labels: User Story, To be verify +labels: enhancement --- ## Description diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00a4d76a..3621cc97 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,126 +1,3 @@ -# Contribute to the development of badaas +# Contributing -- [Tests](#tests) - - [Dependencies](#dependencies) - - [Unit tests](#unit-tests) - - [Integration tests](#integration-tests) - - [Feature tests (of end to end tests)](#feature-tests-or-end-to-end-tests) -- [Logger](#logger) -- [Directory structure](#directory-structure) -- [Git](#git) - - [Branch naming policy](#branch-naming-policy) - - [Default branch](#default-branch) - - [How to release](#how-to-release) - -## Tests - -### Dependencies - -Running tests have some dependencies as: `mockery`, `gotestsum`, etc.. Install them with `make install dependencies`. - -### Unit tests - -We use the standard test suite in combination with [github.com/stretchr/testify](https://github.com/stretchr/testify) to do our unit testing. Mocks are generated using [mockery](https://github.com/vektra/mockery) a mock generator using this command `make test_generate_mocks`. - -To run them, please run: - -```sh -make test_unit -``` - -### Integration tests - -Integration tests have a database and the dependency injection system. - -```sh -make test_integration -``` - -### Feature tests (or end to end tests) - -We use docker to run a Badaas instance in combination with one node of CockroachDB. - -Run: - -```sh -make test_e2e -``` - -The feature files can be found in the `test_e2e/features` folder. - -## Logger - -We use uber's [zap](https://pkg.go.dev/go.uber.org/zap) to log stuff, please take `zap.Logger` as an argument for your services constructors. [fx](https://github.com/uber-go/fx) will provide your service with an instance. - -## Directory structure - -This is the directory structure we use for the project: - -- `configuration/` *(Go code)*: Contains all the configuration keys and holders. Please only use the interfaces, they are all mocked for easy testing. -- `controllers/` *(Go code)*: Contains all the http controllers, they handle http requests and consume services. -- `docker/` : Contains the docker, docker-compose file and configuration files for different environments. - - `test_db/` : Contains the Dockerfile to build a development/test version of CockroachDB. - - `test_api/` : Contains files to build a development/test version of the api. -- `test_e2e/`: Contains all the feature and steps for e2e tests. -- `testintegration/`: Contains all the integration tests. -- `logger/` *(Go code)*: Contains the logger creation logic. Please don't call it from your own services and code, use the dependency injection system. -- `orm/` *(Go code)*: Contains the code of the orm used by badaas. -- `persistance/` *(Go code)*: - - `gormdatabase/` *(Go code)*: Contains the logic to create a database. Also contains a go package named `gormzap`: it is a compatibility layer between *gorm.io/gorm* and *github.com/uber-go/zap*. - - `models/` *(Go code)*: Contains the models (for a structure to me considered a valid model, it has to embed `badaas/orm.UUIDModel` or `badaas/orm.UIntModel`). - - `dto/` *(Go code)*: Contains the Data Transfer Objects. They are used mainly to decode json payloads. - - `pagination/` *(Go code)*: Contains the pagination logic. - - `repository/` *(Go code)*: Contains the repository interfaces and implementations to manage queries to the database. -- `router/` *(Go code)*: Contains http router of badaas. - - `middlewares/` *(Go code)*: Contains the various http middlewares that we use. -- `services/` *(Go code)*: Contains services. - - `auth/protocols/`: Contains the implementations of authentication clients for different protocols. - - `basicauth/` *(Go code)*: Handle the authentication using email/password. - - `sessionservice/` *(Go code)*: Handle sessions and their lifecycle. - - `userservice/` *(Go code)*: Handle users. -- `utils/` *(Go code)*: Contains utility functions that can be used all around the project. -- `validators/` *(Go code)*: Contains validators such as an email validator. - -At the root of the project, you will find: - -- The README. -- The changelog. -- The LICENSE file. - -## Git - -### Branch naming policy - -`[BRANCH_TYPE]/[BRANCH_NAME]` - -- `BRANCH_TYPE` is a prefix to describe the purpose of the branch. - Accepted prefixes are: - - `feature`, used for feature development - - `bugfix`, used for bug fix - - `improvement`, used for refactor - - `library`, used for updating library - - `prerelease`, used for preparing the branch for the release - - `release`, used for releasing project - - `hotfix`, used for applying a hotfix on main - - `poc`, used for proof of concept -- `BRANCH_NAME` is managed by this regex: `[a-z0-9._-]` (`_` is used as space character). - -### Default branch - -The default branch is `main`. Direct commit on it is forbidden. The only way to update the application is through pull request. - -Release tag are only done on the `main` branch. - -### How to release - -We use [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as guideline for the version management. - -Steps to release: - -- Create a new branch labeled `release/vX.Y.Z` from the latest `main`. -- Improve the version number in `changelog.md`. -- Verify the content of the `changelog.md`. -- Commit the modifications with the label `Release version X.Y.Z`. -- Create a pull request on github for this branch into `main`. -- Once the pull request validated and merged, tag the `main` branch with `vX.Y.Z`. -- After the tag is pushed, make the release on the tag in GitHub. +See [this section](./docs/contributing/contributing.md). diff --git a/README.md b/README.md index 376ea1d2..af6ace97 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Badaas provides several key features, each provided by a component that can be u ## Contributing -See [this section](./CONTRIBUTING.md). +See [this section](./docs/contributing/contributing.md). ## Code of Conduct diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md new file mode 100644 index 00000000..8dcf2b77 --- /dev/null +++ b/docs/contributing/contributing.md @@ -0,0 +1,66 @@ +# Contributing + +Thank you for your interest in BaDaaS! This document provides the guidelines for how to contribute to the project through issues and pull-requests. Contributions can also come in additional ways such as joining the [DitRit discord server](https://discord.gg/zkKfj9gj2C), commenting on issues or pull requests and more. + +## Issues + +### Issue types + +There are 3 types of issues: + +- Bug report: You've found a bug with the code, and want to report it, or create an issue to track the bug. +- Discussion: You have something on your mind, which requires input form others in a discussion, before it eventually manifests as a proposal. +- Feature request: Used for items that propose a new idea or functionality. This allows feedback from others before code is written. + +To ask questions and troubleshoot, please join the [DitRit discord server](https://discord.gg/zkKfj9gj2C) (use the BADAAS channel). + +### Before submitting + +Before you submit an issue, make sure you’ve checked the following: + +1. Check for existing issues + - Before you create a new issue, please do a search in [open issues](https://github.com/ditrit/badaas/issues) to see if the issue or feature request has already been filed. + - If you find your issue already exists, make relevant comments and add your reaction. +2. For bugs + - It’s not an environment issue. + - You have as much data as possible. This usually comes in the form of logs and/or stacktrace. +3. You are assigned to the issue, a branch is created from the issue and the `wip` tag is added if you are also planning to develop the solution. + +## Pull Requests + +All contributions come through pull requests. To submit a proposed change, follow this workflow: + +1. Make sure there's an issue (bug report or feature request) opened, which sets the expectations for the contribution you are about to make +2. Assign yourself to the issue and add the `wip` tag +3. Fork the [repo](https://github.com/ditrit/badaas) and create a new [branch](#branch-naming-policy) from the issue +4. Install the necessary [development environment](developing.md#environment) +5. Create your change and the corresponding [tests](developing.md#tests) +6. Update relevant documentation for the change in `docs/` +7. If changes are necessary in [BaDaaS example](https://github.com/ditrit/badaas-example) and [badaas-orm example](https://github.com/ditrit/badaas-orm-example), follow the same workflow there +8. Open a PR (and add links to the example repos' PR if they exist) +9. Wait for the CI process to finish and make sure all checks are green +10. A maintainer of the project will be assigned + +### Use work-in-progress PRs for early feedback + +A good way to communicate before investing too much time is to create a "Work-in-progress" PR and share it with your reviewers. The standard way of doing this is to add a "[WIP]" prefix in your PR’s title and assign the do-not-merge label. This will let people looking at your PR know that it is not well baked yet. + +### Branch naming policy + +`[BRANCH_TYPE]/[BRANCH_NAME]` + +- `BRANCH_TYPE` is a prefix to describe the purpose of the branch. + Accepted prefixes are: + - `feature`, used for feature development + - `bugfix`, used for bug fix + - `improvement`, used for refactor + - `library`, used for updating library + - `prerelease`, used for preparing the branch for the release + - `release`, used for releasing project + - `hotfix`, used for applying a hotfix on main + - `poc`, used for proof of concept +- `BRANCH_NAME` is managed by this regex: `[a-z0-9._-]` (`_` is used as space character). + +## Code of Conduct + +This project has adopted the [Contributor Covenant Code of Conduct](https://github.com/ditrit/badaas/blob/main/CODE_OF_CONDUCT.md) diff --git a/docs/contributing/developing.md b/docs/contributing/developing.md new file mode 100644 index 00000000..6d07b726 --- /dev/null +++ b/docs/contributing/developing.md @@ -0,0 +1,94 @@ +# Developing + +This document provides the information you need to know before developing code for a pull request. + +## Environment + +- Install [go](https://go.dev/doc/install) >= v1.20 +- Install project dependencies: `go get` +- Install [docker](https://docs.docker.com/engine/install/) and [compose plugin](https://docs.docker.com/compose/install/) + +## Directory structure + +This is the directory structure we use for the project: + +- `configuration/`: Contains all the configuration holders. Please only use the interfaces, they are all mocked for easy testing. +- `controllers/`: Contains all the http controllers, they handle http requests and consume services. +- `docker/` : Contains the docker, docker-compose and configuration files for different environments. +- `docs/`: Contains the documentation showed for readthedocs.io. +- `httperrors/`: Contains the http errors that can be responded by the http api. Should be moved to `controller/` when services stop using them. +- `logger/`: Contains the logger creation logic. Please don't call it from your own services and code, use the dependency injection system. +- `mocks/`: Contains the mocks generated with `mockery`. +- `orm/` *(Go code)*: Contains the code of the orm used by badaas. +- `persistance/`: + - `gormdatabase/`: Contains the logic to create a database. Also contains a go package named `gormzap`: it is a compatibility layer between *gorm.io/gorm* and *github.com/uber-go/zap*. + - `models/`: Contains the models. + - `dto/`: Contains the Data Transfer Objects. They are used mainly to decode json payloads. + - `repository/`: Contains the repository interfaces and implementations to manage queries to the database. +- `router/`: Contains http router of badaas and the routes that can be added by the user. + - `middlewares/`: Contains the various http middlewares that we use. +- `services/`: Contains services. + - `auth/protocols/`: Contains the implementations of authentication clients for different protocols. + - `basicauth/`: Handle the authentication using email/password. + - `oidc/`: Handle the authentication via Open-ID Connect. +- `test_e2e/`: Contains all the feature and steps for e2e tests. +- `testintegration/`: Contains all the integration tests. +- `utils/`: Contains functions that can be util all around the project, as managing data structures, time, etc. + +At the root of the project, you will find: + +- The README. +- The changelog. +- The LICENSE file. + +## Tests + +### Dependencies + +Running tests have some dependencies as: `mockery`, `gotestsum`, etc.. Install them with `make install_dependencies`. + +### Linting + +We use `golangci-lint` for linting our code. You can test it with `make lint`. The configuration file is in the default path (`.golangci.yml`). The file `.vscode.settings.json.template` is a template for your `.vscode/settings.json` that formats the code according to our configuration. + +### Unit tests + +We use the standard test suite in combination with [github.com/stretchr/testify](https://github.com/stretchr/testify) to do our unit testing. Mocks are generated using [mockery](https://github.com/vektra/mockery) using the command `make test_generate_mocks`. + +To run them, use: + +```sh +make -k test_unit +``` + +### Integration tests + +Integration tests have a database and the dependency injection system. + +```sh +make test_integration +``` + +### Feature tests (end to end tests) + +These are black box tests that test BaDaaS using its http api. We use docker to run a Badaas instance in combination with one node of CockroachDB. + +Run: + +```sh +make test_e2e +``` + +The feature files can be found in the `test_e2e/features` folder. + +## Requirements + +To be acceptable, contributions must: + +- Have a good quality of code, based on . +- Have at least 80 percent new code coverage (although a higher percentage may be required depending on the importance of the feature). The tests that contribute to coverage are unit tests and integration tests. +- The features defined in the PR base issue must be explicitly tested by an e2e test or by integration tests in case it is not possible (for badaas-orm features for example). + +## Use of Third-party code + +Third-party code must include licenses. diff --git a/docs/contributing/maintaining.md b/docs/contributing/maintaining.md new file mode 100644 index 00000000..44ce9c41 --- /dev/null +++ b/docs/contributing/maintaining.md @@ -0,0 +1,17 @@ +# Maintaining + +This document is intended for BaDaaS maintainers only. + +## How to release + +Release tag are only done on the `main` branch. We use [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as guideline for the version management. + +Steps to release: + +- Create a new branch labeled `release/vX.Y.Z` from the latest `main`. +- Improve the version number in `changelog.md` and `docs/conf.py`. +- Verify the content of the `changelog.md`. +- Commit the modifications with the label `Release version X.Y.Z`. +- Create a pull request on github for this branch into `main`. +- Once the pull request validated and merged, tag the `main` branch with `vX.Y.Z`. +- After the tag is pushed, make the release on the tag in GitHub. diff --git a/docs/index.rst b/docs/index.rst index 3879a83a..b85476db 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,4 +51,12 @@ Learn how to use BaDaaS following the :doc:`badaas/quickstart`. badaas-orm/crud badaas-orm/query badaas-orm/advanced_query - badaas-orm/preloading \ No newline at end of file + badaas-orm/preloading + +.. toctree:: + :caption: Contributing + + contributing/contributing + contributing/developing + contributing/maintaining + Github