Skip to content

Commit

Permalink
docs(contributing): split that of template and project
Browse files Browse the repository at this point in the history
  • Loading branch information
gibbz00 committed Aug 18, 2024
1 parent a0818fc commit 7212116
Show file tree
Hide file tree
Showing 3 changed files with 68 additions and 46 deletions.
47 changes: 2 additions & 45 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,56 +3,13 @@
There are some things that should be kept in mind when contributing to this project.
- Commit messages must follow the [conventional commits](https://www.conventionalcommits.org) specification. This enables automated [CHANGELOG.md](CHANGELOG.md) generation by using [`git-cliff`](https://git-cliff.org).
- Each commit is should pass CI on its own.
- Bug fixes and feature additions should be accompanied by tests.

### Recommended developer tools:

##### LSPs

* [`typos-lsp`](https://github.com/tekumara/typos-lsp)
* [`taplo`](https://github.com/tamasfe/taplo)
* [`rust-analyzer`](https://github.com/rust-lang/rust-analyzer)

{%- if include_precommit -%}
### Using pre-commit hooks

This project makes use of [`pre-commit`](https://pre-commit.com/) hooks. A `pre-commit install` is recommended once the repository has been cloned, unless it has been [auto-enabled](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories).
{%- endif -%}

### Running tests

Pretty standard procedure apart from noting that some tests may be behind feature flags, so:

```sh
cargo test --all-features
```

{%- if include_mdbook -%}
Book testing may be done by:

```sh
mdbook test
```
{%- endif -%}

### Generating and opening documentation

```sh
cargo doc --no-deps --all-features --open
```

{%- if include_mdbook -%}
Book documentation may be generated by installing [`mdbook`](https://rust-lang.github.io/mdBook/guide/installation.html) before running `mdbook serve --open`.
{%- endif -%}

## Release (for maintainers)

1. Make sure CI is not failing.
2. Bump version in the workspace `Cargo.toml` file.
3. Finally:
Make sure CI is not failing. Then:

```sh
# <release> should match [0-9]+.[0-9]+.[0-9]+
# <release> should follow semantic versioning
git commit -am "chore: release <release>"
git tag "<release>"
git cliff -o CHANGELOG.md
Expand Down
60 changes: 60 additions & 0 deletions CONTRIBUTING.md.liquid
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Contributing Guidelines

There are some things that should be kept in mind when contributing to this project.
- Commit messages must follow the [conventional commits](https://www.conventionalcommits.org) specification. This enables automated [CHANGELOG.md](CHANGELOG.md) generation by using [`git-cliff`](https://git-cliff.org).
- Each commit is should pass CI on its own.
- Bug fixes and feature additions should be accompanied by tests.

### Recommended developer tools:

##### LSPs

* [`typos-lsp`](https://github.com/tekumara/typos-lsp)
* [`taplo`](https://github.com/tamasfe/taplo)
* [`rust-analyzer`](https://github.com/rust-lang/rust-analyzer)

{%- if include_precommit -%}
### Using pre-commit hooks

This project makes use of [`pre-commit`](https://pre-commit.com/) hooks. A `pre-commit install` is recommended once the repository has been cloned, unless it has been [auto-enabled](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories).
{%- endif -%}

### Running tests

Pretty standard procedure apart from noting that some tests may be behind feature flags, so:

```sh
cargo test --all-features
```

{%- if include_mdbook -%}
Book testing may be done by:

```sh
mdbook test
```
{%- endif -%}

### Generating and opening documentation

```sh
cargo doc --no-deps --all-features --open
```

{%- if include_mdbook -%}
Book documentation may be generated by installing [`mdbook`](https://rust-lang.github.io/mdBook/guide/installation.html) before running `mdbook serve --open`.
{%- endif -%}

## Release (for maintainers)

1. Make sure CI is not failing.
2. Bump version in the workspace `Cargo.toml` file.
3. Finally:

```sh
# <release> should match [0-9]+.[0-9]+.[0-9]+
git commit -am "chore: release <release>"
git tag "<release>"
git cliff -o CHANGELOG.md
git push && git push --tags
```
7 changes: 6 additions & 1 deletion cargo-generate.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
[template]
ignore = [".github/workflows/ci.yaml", "README.md", "cargo_generate_hooks"]
ignore = [
".github/workflows/ci.yaml",
"CONTRIBUTING.md",
"README.md",
"cargo_generate_hooks",
]

[hooks]
pre = ["cargo_generate_hooks/script.rhai"]

0 comments on commit 7212116

Please sign in to comment.