Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update docs for the v0.5 release #1320

Merged
merged 6 commits into from
Apr 11, 2023
Merged

docs: Update docs for the v0.5 release #1320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2f8909b
WIP
orpheuslummis Apr 10, 2023
3a64ffd
docs: Update docs in light of v0.5
orpheuslummis Apr 10, 2023
b6ab6c9
README fixes
orpheuslummis Apr 11, 2023
32fc52b
apply feedback
orpheuslummis Apr 11, 2023
2e53749
CLI doc update
orpheuslummis Apr 11, 2023
551df7d
Merge branch 'develop' into orpheus/docs/v0.5
orpheuslummis Apr 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 41 additions & 42 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
## Welcome
You have made your way to the contributing guidelines for DefraDB! You are about to be part of a wave making databases decentralized and more powerful.
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.

This document is to help you with the process of contributing to the project. First recommendation is to become familiar with the [project documentation](https://docs.source.network/). Familiarity with [Git](https://training.github.com/), [Go](https://go.dev/doc/install), and [Github](https://docs.github.com/) is assumed.
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.

All contributions are appreciated, whether it's identifying problems, highlighting missing features, or contributing to the codebase in straightforward or complex ways.

You're invited to join the [Source Network Discord](discord.source.network), where you can discuss ideas, ask questions, and find inspiration for what to build next.
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](discord.source.network) to discuss ideas, ask questions, and find inspiration for future developments.

## Getting started
Obtain the repository, then build and run it.
To get started, clone the repository, build, and run it:
```shell
git clone https://github.com/sourcenetwork/defradb.git
cd defradb
Expand All @@ -18,75 +17,75 @@ make start

Refer to the [`README.md`](./README.md) and project documentation for usage examples.


## Development flow

Methodologies the project follows:
The project follows these methodologies:

- **Issue-driven development**: Every pull request links to issue(s).
- **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 of the `<type>: <description>` format in which "type" is one of `feat`, `fix`, `tools`, `docs`, `perf`, `refactor`, `test`, `ci`, `chore`.
- **[Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)**: Every commit message is in the `<type>: <description>` format, where "type" is one of `feat`, `fix`, `tools`, `docs`, `refactor`, `test`, `ci`, `chore`, `bot`.

Basic development flow:
1. Make changes.
2. Usually, write tests of the changed behavior.
3. Ensure that `make test` and `make lint` are passing.

Creating an issue:
1. On [github.com/sourcenetwork/defradb/issues](https://github.com/sourcenetwork/defradb/issues), click "New 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 the issue template.

Submitting a contribution:

1. Fork the repository and with your changes create a branch following the convention `<your-name>/<type>/<description>`, for example `octavio/feat/compression-lru-data`.
2. Create a pull request targeting the `develop` branch. Link the relevant existing issue(s), and create one if no related issue exists yet. Follow the instructions of the pull request template. Use a verb in the PR title to describe the code changes.
3. Read through and accept the Contributor License Agreement, if it's your first contribution.
4. Request review from the *database-team*. Discuss and adapt the pull request accordingly.
5. If approved, click "Squash and merge" to squash it into one commit and to merge in `develop`. Make sure the title of the commit follows the *Conventional Commits* convention.
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.

## Testing
To submit a contribution:
1. Create a branch with your changes following the `<your-name>/<type>/<description>` convention, e.g., `octavio/feat/compression-lru-data`.
2. Create a pull request targeting the `develop` branch. Link to the relevant existing issue(s), and create one if none exists. Follow the pull request template instructions and use a verb in the PR title to describe the code changes.
3. Read and accept the Contributor License Agreement, if it's your first contribution.
4. Request a review from the *database-team*. Discuss and adapt the pull request as needed.
5. Once approved, click "Squash and merge" to squash the commits into one and merge them into the `develop` branch. Ensure that the commit title follows the *Conventional Commits* convention.

`make test` to run the unit tests and integration tests.

`make lint` to run the linters.
When introducing breaking changes, include the `BREAKING CHANGE` keyword in the commit message body, followed by a description of the change. This helps keep track of changes that may require additional attention or migration steps.

`make bench` to run the benchmark suite. To assess the difference between a branch's results and the `develop` branch's results, execute the suite on both outputting the results to files, and compare the two with e.g. `benchstat develop.txt current.txt`. To install `benchstat` use `make deps:bench`.
## Testing

`make test:changes` to run a test suite detecting breaking changes. Breaking changes need to be accompanied by documentation in `docs/data_format_changes/` for the test to pass.
Run the following commands for testing:

- `make test` to run unit and integration tests.
- `make lint` to run linters.
- `make bench` to run the benchmark suite. To compare a branch's results with the `develop` branch results, execute the suite on both branches, output the results to files, and compare them with a tool like `benchstat` (e.g., `benchstat develop.txt current.txt`). To install `benchstat`, use `make deps:bench`.
- `make test:changes` to run a test suite detecting breaking changes. Accompany breaking changes with documentation in `docs/data_format_changes/` for the test to pass.

## Documentation
The overall project's documentation is 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).
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).

The code documentation, doc comments, can be viewed as a website:
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
```
- [go.dev/doc/comment](https://go.dev/doc/comment) has guidelines on writing Go doc comments.

`docs/cmd/` is where auto-generated documentation of the `defradb` command-line program is.
- Refer to [go.dev/doc/comment](https://go.dev/doc/comment) for guidelines on writing Go doc comments.

`docs/data_format_changes/` details the historical breaking changes to data persistence.
The `docs/cmd/` directory contains auto-generated documentation for the `defradb` command-line program.

The `docs/data_format_changes/` directory provides details on the historical breaking changes to data persistence.

## Additional information

This section includes good-to-know information for advanced contributors.
This section contains useful information for advanced contributors.

Dependency management:
- `go mod tidy` should be performed by pull requests changing dependency requirements.
- The project uses `dependabot` for automatic creation of pull requests updating dependencies.
- Run `go mod tidy` for pull requests that change dependency requirements.
- The project uses `dependabot` to automatically create pull requests for updating dependencies.

Peer review of pull requests:
- Using the [Conventional Comments](https://conventionalcomments.org/) methodology is recommended.
- It is recommended to use the [Conventional Comments](https://conventionalcomments.org/) methodology.

Licensing:
- The [BSL license header](./licenses/BSL.txt) must be included at the top of every code file.
- Include the [BSL license header](./licenses/BSL.txt) at the top of every code file.

Project management:
- [Milestones](https://github.com/sourcenetwork/defradb/milestones) and a [project board](https://github.com/orgs/sourcenetwork/projects/3) are used to coordinate work on releases.
- Use [Milestones](https://github.com/sourcenetwork/defradb/milestones) and a [project board](https://github.com/orgs/sourcenetwork/projects/3) to coordinate work on releases.

The community follows the [Source Improvement Proposals](https://github.com/sourcenetwork/SIPs/) process for more comprehensive changes.
Loading