oxidetalis/CONTRIBUTING.md

# Contributing to oxidetalis

Thank you for your interest in contributing to oxidetalis! We welcome
contributions from the community to help improve OxideTalis and make it even
better.

## Code of Conduct

We have a [Code of Conduct](./CODE_OF_CONDUCT.md) that we expect all
contributors to follow. Please read the Code of Conduct before making a
contribution to OxideTalis. If you encounter any behavior that violates the Code
of Conduct, please report it to the maintainers at <otmp@4rs.nl>.

## Reporting Issues

If you encounter any issues or bugs while using oxidetalis, please open a new
issue on our [issue tracker][issue-tracker]. When reporting an issue, please provide as much
detail as possible, including steps to reproduce the issue and any relevant
error messages.

## Feature Requests

If you have a feature request or an idea for improving oxidetalis, we encourage
you to open a new issue on our [issue tracker][issue-tracker]. Please describe the feature or
improvement in detail and provide any relevant context or examples.

## Contributors list

We have a list of contributors in the `CONTRIBUTORS.md` file. If your email is
public, we will add you to the list. If you don't want to be added, please let
us know.

## Developer Certificate of Origin (DCO)

Please note that all contributions to oxidetalis must be made under the terms of
the Developer Certificate of Origin (DCO). This is a legal statement that
certifies that you have the right to contribute the code and that you agree to
license it under the project's licenses. Please read the DCO carefully before
making a contribution, you can find the DCO here [DCO](./DCO).

To indicate that you agree to the terms of the DCO, you can add a
`Signed-off-by` line to your commit messages. This can be done by adding the
`-s` flag to the `git commit` command, for example:

```bash
git commit -s -m "feat: Add new feature"
```

> **Note**
>
> We will not accept contributions that do not include the `Signed-off-by` line
> in the commit message. We may ask you to re-submit your contribution with the
> `Signed-off-by` line if it is missing.

## Claiming an issue

If the issue is not assigned to anyone, you can claim it by commenting on the
issue that you want to work on it. One of the maintainers will then assign the
issue to you. 

If the issue is already assigned to someone and they have not made any progress
within two weeks, you can comment that you would like to take over. The
maintainers will reassign the issue to you if the original assignee agrees or
does not respond.

Issue assignment operates on a first-come, first-served basis. If you are
assigned an issue, please ensure you work on it promptly. If you are unable to
continue for any reason, notify us so we can reassign it to another contributor.

This process helps ensure that issues are addressed promptly and that
contributors avoid duplicating work or experiencing long wait times for
responses.

## Writing Code

Before you start writing code, please open a new [issue][issue-tracker] first to
discuss the proposed changes. This will help ensure that your contribution is
aligned with the project's goals and that you are not duplicating work that is
already in progress or has been completed by someone else.

After your issue has confirmed, you can start writing code. then open your PR at
our [Forgejo](https://git.4rs.nl/OxideTalis/oxidetalis/pulls) instance and
follow the guidelines below.

### Rust Version

In the oxidetalis project, we always try to stay on the lowest MSRV possible for
compatibility, but the development process relies on the nightly release to get
the latest rust-analyzer and rustfmt features.

You can check the nightly version used in the project in the `rust-toolchain`
file. And the MSRV in the `Cargo.toml` file.

### PR title

Your PR will squash and merge, and your PR title will be used as the commit
message. Please make sure your PR title is clear and concise.

The title must follow [Conventional Commits] format. This means that the title
should be in the following format:

```
<type>(<scope>): <description>
```

- The `<scope>` is optional, and the `<description>` should be a clear and
  concise summary of the changes.
- You should use the imperative, present tense (e.g., "Add feature" instead of
  "Added feature").
- The `<type>` should be one of the following:
  - `feat`: A new feature
  - `fix`: A bug fix
  - `docs`: Documentation changes
  - `refactor`: Refactoring code without changing its behavior
  - `change`: Changes that affect the meaning of the code
  - `deprecate`: Changes that deprecate a part of the code
  - `remove`: Changes that remove a deprecated part of the code
  - `security`: Changes that affect the security of the code
  - `perf`: A code change that improves performance
  - `test`: Adding missing tests or correcting existing tests
  - `chore`: Changes to the build process or auxiliary tools and libraries such
    as documentation generation

#### Example

```
- feat: something
- chore(ci): update MSRV
```

### PR description

Your PR description should provide a clear and concise summary of the changes
you have made. It should also include any relevant context or background
information that will help the project maintainers understand the purpose of the
changes. Make sure to reference the issue that your PR is addressing, and note
any breaking changes that your PR introduces.

Make sure to explain why you made the changes not just what changes you made.

### Code Style

Please follow the existing code style and conventions used in the oxidetalis
project. This includes:

- Using Rust's official formatting tool, `rustfmt`, to format your code.
- Writing clear and concise code with meaningful variable and function names.
- Adding comments to explain complex logic or algorithms.

### CI

Run the CI before submitting your code. You can run the CI with the following
command:

```bash
just ci
```

This will run the tests and check the code formatting. If the CI fail, please
fix the issues before submitting your code.

## Code Review

All contributions to oxidetalis will go through a code review process. This
ensures that the code meets the project's standards and maintains its quality.
Please be open to feedback and suggestions from the project maintainers during
the code review process.

### Review Process

When you submit your pull request (PR), you can request a review from the maintainers. The PR will be marked as `Waiting On Review` until a maintainer reviews it. There are two possible outcomes:

#### If the PR is approved
The PR will be marked as `Approved`, and the maintainer will merge it.

#### If the PR is not approved (requested changes)
The PR will be marked as `Waiting On Author`. You will need to make the requested changes or discuss them with the maintainer. After making the necessary updates, you can request a review again.

## Maintainers

As a maintainer, after approving a PR, you need to pull the PR locally and then merge it manually.

Why? Because Forgejo add some trailers to the commit message, so you need to merge it manually.

### Pull the PR

```bash
# Replace {{pr-number}} with the PR number
git fetch origin +refs/pull/{{pr-number}}/head:refs/heads/pr-{{pr-number}}
```

### Merge the PR

There is important trailers you must add it to the commit message, which is:
- `Signed-off-by: Name <email>`: The name and email of you, the maintainer.
- `Reviewed-on: pr-url`: The URL of the PR on Forgejo.
- `Reviewed-by: Name <email>`: The name and email of the reviewer, can be you and other reviewers (each reviewer in a new line).
- `Co-committed-by: Name <email>`: The name and email of the PR author.
- `Reported-by: Name <email>`: The name and email of the person who reported the issue (if any bug).
- `Suggested-by: Name <email>`: The name and email of the person who suggested the feature (if any feature).
- `Fixes: issue-url`: The URL of the issue that the PR fixes (if any).

Things to note:
- You can add more than one `Reviewed-by` trailer.
- You need to make sure to not commit the changes as author, you need to commit it as the author of the PR. you are the committer, not the author.
- The commit subject must be in the [Conventional Commits] format. To generate the changelog correctly.

```bash
# Replace {{pr-number}} with the PR number
git merge --squash pr-{{pr-number}}
git commit -s --author "Name <email>" -m "feat: Add new feature

Reviewed-on: https://git.4rs.nl/OxideTalis/oxidetalis/pulls/{{pr-number}}
Reviewed-by: Name <email>
Co-committed-by: Name <email>
Reported-by: Name <email>
"
```

### Push the changes

```bash
git push origin master
```

### Mark the PR as merged manually

Copy the full commit hash and mark the PR as merged manually on Forgejo.

That's it! You have merged the PR manually. Thank you for your contribution!

## License

By contributing to oxidetalis, you agree that your contributions will be
licensed under the project's licenses. Each crate in the project has its own
license, so please make sure you are aware of the license terms before making a
contribution.

Happy contributing!

[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/
[issue-tracker]: https://git.4rs.nl/OxideTalis/oxidetalis/issues