Skip to content

Commit

Permalink
docs: added section on dev tools and process to CONTRIBUTING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
fujiapple852 committed Dec 24, 2024
1 parent b426c8d commit ddd54f5
Showing 1 changed file with 151 additions and 3 deletions.
154 changes: 151 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,160 @@
# Contributing to Trippy

Contributions to Trippy are most welcome, whether you wish to report a bug, submit a fix or feature or request a
feature.
Contributions to Trippy are most welcome, whether you wish to report a bug, request a feature, or contribute code.

Raise issues and feature requests in the GitHub [issue tracker](https://github.com/fujiapple852/trippy/issues) and raise
all changes as GitHub [pull requests](https://github.com/fujiapple852/trippy/pulls).

## Release instructions
## Development

This section describes how to set up a development environment and the development process for Trippy.

### Development tools

The following tools are needed for local development. Note that most of the following are checked during CI, so it is
recommended to run these checks locally before submitting a pull request.

#### Rust

Trippy is written in [`Rust`](https://www.rust-lang.org/tools/install) and requires the Rust toolchain to build and run.
As well as default components such as `cargo`, you will need `rustfmt` and `clippy` for code formatting and linting.

> [!NOTE]
> Trippy uses the `stable` toolchain.
To install `rustfmt` and `clippy`:

```shell
rustup component add rustfmt clippy
```

To format the Rust code:

```shell
cargo fmt --all
```

> [!NOTE]
> Trippy uses default settings for code formatting.
To lint the Rust code:

```shell
cargo clippy --workspace --all-features --tests -- -Dwarnings
```

> [!NOTE]
> Clippy configuration is defined at the workspace level in the root `Cargo.toml` file.
#### Cargo `deny`

If you add or update dependencies, you must run Cargo [`deny`](https://github.com/EmbarkStudios/cargo-deny) to ensure
that the licenses of the dependencies are acceptable.

```shell
cargo deny check --hide-inclusion-graph
```

The allowed licenses are defined in the `deny.toml` file.

#### Cargo `insta`

If you make changes that impact the command line interface arguments, manual pages or shell completions, you must update
the testing snapshots using Cargo [`insta`](https://insta.rs).

After making your changes, run `cargo test` to generate the new snapshots followed by `cargo insta` to review and update
the snapshots.

```shell
cargo test && cargo insta review
```

#### Cargo `spelling`

If you make changes to code documentation, you must run Cargo [`spellcheck`](https://github.com/drahnr/cargo-spellcheck)
to ensure they are free from misspellings and typos.

To check the spelling:

```shell
cargo spellcheck check
```

The configuration for `spellcheck` is defined in the `.config/spellcheck.toml` file and the custom dictionary is defined
in the `.config/trippy.dic` file.

#### Cargo `msrv`

If you add or update dependencies, you should use the Cargo [msrv](https://github.com/foresterre/cargo-msrv) tool to
check the Minimum Supported Rust Version (MSRV) to ensure that the new dependencies are compatible with the current
MSRV.

To check the MSRV of the `trippy` crate:

```shell
cargo msrv verify --manifest-path crates/trippy/Cargo.toml-- cargo check
```

#### `dprint`

The [`dprint`](https://dprint.dev/) tool is needed to ensure consistent formatting of the non-Rust portions of the
codebase and docs.

To format the non-Rust code:

```shell
dprint fmt
```

The configuration for `dprint` is defined in the `dprint.json` file.

#### Docker

If you make changes to the `Dockerfile`, you should build the Docker image locally to ensure it builds correctly.

```shell
docker build . -t trippy:dev
```

> [!NOTE]
> If you add new files that are required at build time then you must update the `Dockerfile` to include them explicitly.
### Development process

This section describes the development process for Trippy.

#### Conventional commits

All commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.

The commit message should be structured as follows:

```text
<type>[optional scope]: <description>
```

Where `type` is one of the following:

- `feat`: A new feature
- `fix`: A bug fix
- `chore`: Build process, dependency and version updates
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `test`: Adding missing tests or correcting existing tests
- `build`: Changes that affect the build system or external dependencies
- `ci`: Changes to our CI configuration files and scripts
- `revert`: Reverts a previous commit

The `scope` is optional and, if given, should be the name of the crate being modified, currently one of `core`,
`packet`, `dns`, `privilege`, `tui` or `trippy`.

> [!NOTE]
> Small do-one-things commits are preferred over large do-many-things commits. This makes changes easier to review and
> revert if necessary. For example, if you are adding a new feature and fixing a bug, it is better to create two
> separate commits.
## Releases

Instructions for releasing a new `0.xx.0` version of Trippy.

Expand Down

0 comments on commit ddd54f5

Please sign in to comment.