From 26b2b78867d655609e2954279edc0df4d91e8468 Mon Sep 17 00:00:00 2001 From: Shahzad Lone Date: Mon, 10 Mar 2025 10:31:44 -0400 Subject: [PATCH] PR(FIX): Revamp CONTRIBUTING guidlines. --- CONTRIBUTING.md | 270 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 210 insertions(+), 60 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a495502a22..a3b723f2f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,54 @@ -## Welcome -You have made your way to the contributing guidelines of DefraDB! You are about to be part of a wave making databases decentralized and more powerful. +## Contributing to DefraDB -This document will guide you through the process of contributing to the project. It is recommended that you familiarize yourself with the [project documentation](https://docs.source.network/), [Git](https://training.github.com/), [Go](https://go.dev/doc/install), and [Github](https://docs.github.com/) before getting started. +Thank you for your interest in contributing to DefraDB! You're about to join a wave of innovation in decentralized and powerful databases. +This guide will help you navigate the contribution process, whether you're identifying issues, suggesting features, or contributing code. -All contributions are appreciated, whether it's identifying problems, highlighting missing features, or contributing to the codebase in simple or complex ways. -You are encouraged to join the [Source Network Discord](https://discord.gg/w7jYQVJ) to discuss ideas, ask questions, and find inspiration for future developments. +It is recommended that before you begin, familiarize yourself with the following: +- [Project documentation](https://docs.source.network/) +- [Git](https://training.github.com/) +- [GitHub](https://docs.github.com/) +- [Go](https://go.dev/doc/install) +- [Cargo/rustc](https://doc.rust-lang.org/cargo/commands/cargo-rustc.html), typically installed via [rustup](https://www.rust-lang.org/tools/install) +- [SourceHub](https://github.com/sourcenetwork/sourcehub) +- [Ollama](https://ollama.com/download) + +We also encourage you to join the [Source Network Discord](https://discord.gg/w7jYQVJ) to discuss ideas, ask questions, and find inspiration for future developments. + +## Documentation +The overall project documentation can be found at [docs.source.network](https://docs.source.network), and its source at [github.com/sourcenetwork/docs.source.network](https://github.com/sourcenetwork/docs.source.network). + +To view the code documentation (doc comments) as a website, follow these steps: +```shell +go install golang.org/x/pkgsite/cmd/pkgsite@latest +cd your-path-to/defradb/ +pkgsite +# open http://localhost:8080/github.com/sourcenetwork/defradb +``` +- Refer to [go.dev/doc/comment](https://go.dev/doc/comment) for guidelines on writing Go doc comments. + +- The `docs/website/references/http/openapi.json/` directory contains auto-generated http api documentation. + +- The `docs/website/references/cli/` directory contains auto-generated cli documentation. + +### Manpages + +We do support manpages, in order to get them working please do: + +```sh +make docs:manpages +``` + +Then the man pages will be in `build/man/` directory. + +You can install them manually on your system, or if you are on linux you can do: + +```sh +make install:manpages +``` + +## Getting Started -## Getting started To get started, clone the repository, build, and run it: ```shell git clone https://github.com/sourcenetwork/defradb.git @@ -17,83 +58,192 @@ make start Refer to the [`README.md`](./README.md) and project documentation for usage examples. -## Development flow - -The project follows these methodologies: - -- **Issue-driven development**: Every pull request is linked to one or more issues. -- **[Squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)**: Commits of a pull request are squashed into one before being merged onto the `develop` branch. -- **[Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)**: Every commit message is in the `: ` format, where "type" is one of `feat`, `fix`, `tools`, `docs`, `refactor`, `test`, `ci`, `chore`, `bot`. - +## Creating an Issue -To create an issue: 1. Go to [github.com/sourcenetwork/defradb/issues](https://github.com/sourcenetwork/defradb/issues), and click "New issue". 2. Select the relevant issue type. 3. Fill out the issue template. -Follow this basic development flow: -1. Make changes. -2. Write tests for the changed behavior, if applicable. -3. Ensure that `make test` and `make lint` are passing. +## Git Workflow + +### Fork Flow vs Branch Flow + +We have adopted the Git Fork Flow as our primary development workflow for both internal and external developers. This decision was made to ensure a consistent and streamlined approach to contributions across our project. + +### Fork Flow for All Contributors + +All developers, whether internal or external, are expected to use the Fork Flow for their contributions. This involves: + +1. Forking the main repository. +2. Cloning your forked repository locally. +3. Creating a feature branch on the clone of your forked repository. +4. Making changes on the feature branch. +5. Writing tests for the changed behavior, if applicable. +6. Ensuring that all the `make` target checks are passing: + - `make docs` + - `make mocks` + - `make lint` + - `make tidy` + - `make test` + - `make test:changes` +7. Committing your changes on to the feature branch. +8. Pushing your feature branch with the commit changes, on to your fork. +9. [Opening a pull request](#opening-pull-request) from your branch on your fork, targeting the `develop` branch of the main repository. + +### Limited Use of Branch Flow + +In certain circumstances, internal developers may need to use the Branch Flow, particularly for CI-related updates that require direct access to the main repository. If an internal developer opts to use the Branch Flow, it will look something like this: + +1. Clone the main repository locally. +2. Create a feature branch on the clone, adhering to the following branch naming convention + ``` + /