diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..7dc6859 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,247 @@ +# Contributing + +Thank you for investing your time in contributing to this project! + +**Contributions of all sizes welcome and valued here.** + +To get an overview of the project's best practices, tooling, and automation, +read the [rationale](#rationale). + +In this guide you will get an overview of the contribution workflow from +opening an issue, creating a PR, reviewing, and merging the PR. + +## Conduct + +This project adheres to the [Rust Code of Conduct](./CODE_OF_CONDUCT.md). This describes +the _minimal_ behavior expected from all contributors. + +## New contributor guide + +Some resources to help you get started with open source contributions: + +- [Finding ways to contribute to open source on +GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) +- [Set up +Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) +- [Collaborating with pull +requests](https://docs.github.com/en/github/collaborating-with-pull-requests) + +## Contributing in issues + +For any issue, the three fundamental ways an individual can contribute: + +1. By opening the issue for discussion: For instance, if you believe that you + have discovered a bug. + +2. By helping to triage the issue: Providing supporting details (a test case + that demonstrates a bug), providing suggestions on how to deal with the +issue, or ensuring that the issue has appropriate tags. + +3. By helping to resolve the issue: Typically either in the form of + demonstrating that the issue reported ain't a problem after all, or more +often, by opening a Pull Request that changes some bit of something in a +concrete and reviewable manner. + +**Anybody can partake in any stage of contribution**. This project encourages +you to partake in the discussion around bugs and partake in reviewing pull +requests. + +### Asking for general help + +If you have reviewed existing documentation and still have questions or +problems, you can [open a +discussion](https://github.com/gacallea/freesound-credits/discussions/new) +asking for help. + +In exchange for receiving help, this project asks that you contribute back a +documentation PR that helps others avoid the problems that you encountered. + +### Submitting a bug report + +If you spot a problem, [search if an issue already +exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). +If a related issue doesn't exist, you can open a new issue using a relevant +[issue +form](https://github.com/gacallea/freesound-credits/issues/new/choose). Please +fill out this form, following the template to the best of your ability. + +The two most important pieces of information: a description of the behavior +you see and a test case to recreate the problem. See [How to create a +Minimal, Complete, and Verifiable +example](https://stackoverflow.com/help/mcve). + +### Triaging a bug report + +Common practice includes having a discussion around open issues. Some +contributors may have differing opinions about the issue, including whether the +behavior constitute a bug or a feature. This discussion should stay focused, +helpful, and professional. + +Short, clipped responses that give neither added context nor supporting detail +ain't helpful nor professional. To most, such responses result annoying and +unfriendly. + +This project encourages contributors to help one another make forward progress +as much as possible. Empowering one another to solve issues collaboratively. +Wether you feel either doesn't qualify as a problem, or if you happen upon +information that you feel incongruous. When commenting on an issue, explain why +you feel that way. With supporting context. Willing to concede misconstruing. +By doing so, often leads the correct outcome much faster. + +### Resolving a bug report + +In the majority of cases, resolving issues involve opening a Pull Request. The +process for opening and reviewing a Pull Request resembles that of opening and +triaging issues. Although it carries with it a necessary review and approval +workflow that ensures that the proposed changes meet the minimal quality and +functional guidelines of the project. + +## Making changes + +Besides standardized [tooling](https://www.rust-lang.org/tools) and +[conventions](https://doc.rust-lang.org/beta/style-guide/index.html), default +`rustfmt` and `clippy`, this project relies on [RustSec](https://rustsec.org) +to inspect supply chain, and [`trufflehog`](https://trufflesecurity.com) to +avoid any secrets in the code base. To fix [the crate documentation +comments](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments) +and avoid typos in the source tree, this project relies on `cargo-spellcheck`. +Likewise, this project relies on +[`markdownlint-cli2``](https://github.com/DavidAnson/markdownlint-cli2) and +[`pre-commit-hooks`](https://github.com/pre-commit/pre-commit-hooks). This is +all conveniently enforced with [Git Hooks](https://githooks.com). + +### Local requirements + +> [!IMPORTANT] +> Contributors necessarily need installing and perusing tooling +> locally guaranteeing contracts before committing any changes. + +- [Set up Rust](https://www.rust-lang.org/tools/install) with `rustup`: `curl +--proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` +- Install [`cargo +audit`](https://github.com/rustsec/rustsec/blob/main/cargo-audit/README.md): +`cargo install cargo-audit --locked` +- Install [`cargo +auditable`](https://github.com/rust-secure-code/cargo-auditable): `cargo +install cargo-auditable --locked` + - Set up a [shell alias for `cargo + auditable`](https://github.com/rust-secure-code/cargo-auditable?tab=readme-ov-file#can-i-make-cargo-always-build-with-cargo-auditable) +- Install [`cargo deny`](https://embarkstudios.github.io/cargo-deny/): `cargo +install --locked cargo-deny` +- Install `cargo-spellcheck`: `cargo install --locked cargo-spellcheck` +- Install [`trufflehog`](https://trufflesecurity.com/trufflehog): `brew install +trufflehog` + - Otherwise, download a binary from [`trufflehog` release + page](https://github.com/trufflesecurity/trufflehog/releases). +- Install [`pre-commit`](https://pre-commit.com): `pip install pre-commit` + +### Make changes locally + +- 1 Fork the repository. + +- Using GitHub Desktop: + - [Getting started with GitHub + Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) + will guide you through setting up Desktop. + - Once you set up Desktop, you can use it to [fork the + repository](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)! + +- Using the command line: + - [Fork the + repository](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) + so that you can make your changes without affecting the original project + until you're ready to merge them. + +- 2 Install `pre-commit` [Git Hooks](https://githooks.com) with `pre-commit +install --install-hooks` + +- 3 Create a working branch and start with your changes! + +### Commit your update + +Before committing any changes, make sure to run `pre-commit run --all-files` +and that it returns no issues. Should it present any warning or issue: please +fix, rinse, and repeat. + +Once happy with them, commit the changes. Make sure to use "[Conventional +Commits](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits)". + +### Pull request + +When you completed the changes, create a pull request, also known as a PR. + +- Fill the "Ready for review" template so that we can review your PR. This +template helps reviewers understand your changes as well as the purpose of your +pull request. +- Don't forget to [link PR to +issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) +if you are solving one. +- Enable the checkbox to [allow maintainer +edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) +so the branch can be updated for a merge. Once you submit your PR, a Docs team +member will review your proposal. We may ask questions or request additional +information. +- We may ask for changes to be made before a PR can be merged, either using +[suggested +changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) +or pull request comments. You can apply suggested changes directly through the +UI. You can make any other changes in your fork, then commit them to your +branch. +- As you update your PR and apply changes, mark each conversation as +[resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations). +- If you run into any merge issues, checkout this [git +tutorial](https://github.com/skills/resolve-merge-conflicts) to help you +resolve merge conflicts and other issues. + +### Your PR is merged + +Congratulations :tada::tada: The `freesound-credits` team thanks you +:sparkles:. + +Once your PR is merged, your contributions will be publicly visible on the +[GitHub docs](https://docs.github.com/en). + +Now that you are part of the GitHub docs community, see how else you can +[contribute to the docs](/contributing/types-of-contributions.md). + +## Rationale + +This project adheres to [Conventional +Commits](https://www.conventionalcommits.org/en/v1.0.0/), [Semantic +Versioning](https://semver.org/spec/v2.0.0.html), and [Keep a +Changelog](https://keepachangelog.com/en/1.0.0/). It also strives, in [a +constantly evolving +process](https://www.schneier.com/essays/archives/2000/04/the_process_of_secur.html), +to apply [AppSec](https://www.ibm.com/topics/application-security) [during +the entire development life +cycle](https://www.youtube.com/watch?v=hDvz8KivY_U), as best as it can. + +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), +[Semantic Versioning](https://semver.org/spec/v2.0.0.html), and [Keep a +Changelog](https://keepachangelog.com/en/1.0.0/) can profoundly intertwine and, +when so, they must seamlessly work in concert to fully appreciate their +benefits. With Conventional Commits as the Gordian Knot of automation arising +from combining these best practices, guaranteeing that all commits adhere to it +becomes paramount. + +### Guaranteeing contract + +Manually enforcing best practices and guaranteeing contracts in a code base and +onto contributors befalls under the inadequate and cumbersome category. Thus, +this project relies on both [local tooling](#local-requirements) together with CI +pipelines, to make sure any changes pushed to this repository don't +break contract. + +### Fully automated releases + +Appropriately implementing the afore mentioned best practices opens the door to +[Fully Automated Releases](https://blog.orhun.dev/automated-rust-releases/). +For this purpose, This project relies on +[release-plz](https://release-plz.ieni.dev). To [automate +changelog](https://release-plz.ieni.dev/docs/changelog-format). To handle +dependency updates. To handle [version +management](https://release-plz.ieni.dev/docs/semver-check) and +[crates.io](https://crates.io) releases. Upon successful release pipelines, +`release-plz` invokes [cargo-dist](https://opensource.axo.dev/cargo-dist/) to +create GitHub releases and packaging for various platforms, along with binary +artifacts and installers.