move contributing docs to readthedocs

.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
 

.github/ISSUE_TEMPLATE/discussion.md

@@ -0,0 +1,7 @@
+---
+name: Discussion
+about: Start a discussion for BaDaaS
+title: ''
+labels: question
+---
+<!-- Please join the DitRit discord server https://discord.gg/zkKfj9gj2C to ask questions and troubleshoot (use the BADAAS channel). For all other design discussions please continue. -->

.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

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 <https://gorm.io> 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).

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
 

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)

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 <https://gorm.io> 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 <https://go.dev/doc/effective_go>.
+- 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.

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.

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
+   badaas-orm/preloading
+
+.. toctree::
+   :caption: Contributing
+
+   contributing/contributing
+   contributing/developing
+   contributing/maintaining
+   Github <https://www.github.com/ditrit/badaas>