diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f44b578..41aceca 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,4 +1,4 @@ # IMPORTANT: REPLACE THE BELOW HANDLE AND THE PLACEHOLDERS FURTHER BELOW WITH HANDLES OF THE ACTUAL CODE OWNERS!!! * @0xNeshi -# SECURITY.md {{code-owner-1}} {{code-owner-2}} @OpenZeppelin/product-security +# SECURITY.md @0xNeshi @OpenZeppelin/product-security diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 808987f..2d3a23e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -35,7 +35,7 @@ body: id: terms attributes: label: Contribution Guidelines - description: By submitting this issue, you agree to follow our [Contribution Guidelines](https://github.com/0xNeshi/robust-rust-lib-template/blob/master/CONTRIBUTING.md) + description: By submitting this issue, you agree to follow our [Contribution Guidelines](https://github.com/OpenZeppelin/rust-project-template/blob/master/CONTRIBUTING.md) options: - label: I agree to follow this project's Contribution Guidelines required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index b0f1e37..e01e139 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -18,7 +18,7 @@ body: id: terms attributes: label: Contribution Guidelines - description: By submitting this issue, you agree to follow our [Contribution Guidelines](https://github.com/0xNeshi/robust-rust-template-lib/blob/master/CONTRIBUTING.md) + description: By submitting this issue, you agree to follow our [Contribution Guidelines](https://github.com/OpenZeppelin/rust-project-template/blob/master/CONTRIBUTING.md) options: - label: I agree to follow this project's Contribution Guidelines required: true diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 850ba92..06828a2 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -1,4 +1,4 @@ -# This workflow runs whenever a PR is opened or updated, or a commit is pushed to main. It runs +# This workflow runs whenever a PR is opened or updated, or a commit is pushed to master. It runs # several checks: # - fmt: checks that the code is formatted according to rustfmt # - clippy: checks that the code does not contain any clippy warnings @@ -10,12 +10,12 @@ permissions: contents: read # This configuration allows maintainers of this repo to create a branch and pull request based on -# the new branch. Restricting the push trigger to the main branch ensures that the PR only gets +# the new branch. Restricting the push trigger to the master branch ensures that the PR only gets # built once. on: push: - branches: [main] + branches: [master] pull_request: # If new code is pushed to a PR branch, then cancel in progress workflows for that PR. Ensures that @@ -23,21 +23,22 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true + jobs: fmt: runs-on: ubuntu-latest - name: stable / fmt + name: nightly / fmt steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # tag=v6.0.2 with: submodules: true - - name: Install stable + - name: Install nightly Rust uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # branch=master with: - toolchain: stable + toolchain: nightly components: rustfmt - - name: cargo fmt --check - run: cargo fmt --check + - name: cargo fmt --all --check + run: cargo +nightly fmt --all --check clippy: runs-on: ubuntu-latest name: ${{ matrix.toolchain }} / clippy @@ -63,7 +64,10 @@ jobs: with: reporter: 'github-pr-check' github_token: ${{ secrets.GITHUB_TOKEN }} + clippy_flags: --all-targets --all-features -- -D warnings -D clippy::all -D clippy::pedantic semver: + # REMOVE THE `if` CHECK AFTER FIRST PUBLISH TO crates.io + if: ${{ false }} runs-on: ubuntu-latest name: semver steps: @@ -95,6 +99,8 @@ jobs: uses: dtolnay/install@982daea0f5d846abc3c83e01a6a1d73c040047c1 # branch=cargo-docs-rs - name: cargo docs-rs run: cargo docs-rs + env: + RUSTUP_TOOLCHAIN: nightly hack: # cargo-hack checks combinations of feature flags to ensure that features are all additive # which is required for feature unification @@ -123,7 +129,7 @@ jobs: # https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability strategy: matrix: - msrv: ["1.56.1"] # 2021 edition requires 1.56 + msrv: ["1.85.0"] # 2024 edition requires 1.85.0 name: ubuntu / ${{ matrix.msrv }} steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # tag=v6.0.2 diff --git a/.github/workflows/nostd.yml b/.github/workflows/nostd.yml index 2d63173..495af14 100644 --- a/.github/workflows/nostd.yml +++ b/.github/workflows/nostd.yml @@ -1,14 +1,20 @@ # This workflow checks whether the library is able to run without the std library (e.g., embedded). -# This entire file should be removed if this crate does not support no-std. See check.yml for -# information about how the concurrency cancellation and workflow triggering works +# It is disabled by default. To enable it for a no_std project, remove the `workflow_dispatch` +# trigger below and uncomment the following triggers: +# push: +# branches: [master] +# pull_request: +# Also ensure the crate declares `#![no_std]` (or `#![cfg_attr(not(feature = "std"), no_std)]`) +# and that `--no-default-features` disables the std feature. name: no-std permissions: contents: read on: - push: - branches: [main] - pull_request: + # push: + # branches: [master] + # pull_request: + workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} diff --git a/.github/workflows/safety.yml b/.github/workflows/safety.yml index c0d5810..57b1987 100644 --- a/.github/workflows/safety.yml +++ b/.github/workflows/safety.yml @@ -11,7 +11,7 @@ permissions: on: push: - branches: [main] + branches: [master] pull_request: concurrency: @@ -51,12 +51,14 @@ jobs: env: ASAN_OPTIONS: "detect_odr_violation=0:detect_leaks=0" RUSTFLAGS: "-Z sanitizer=address" + RUSTUP_TOOLCHAIN: nightly - name: cargo test -Zsanitizer=leak if: always() run: cargo test --all-features --target x86_64-unknown-linux-gnu env: LSAN_OPTIONS: "suppressions=lsan-suppressions.txt" RUSTFLAGS: "-Z sanitizer=leak" + RUSTUP_TOOLCHAIN: nightly miri: runs-on: ubuntu-latest steps: @@ -74,18 +76,21 @@ jobs: run: cargo miri test env: MIRIFLAGS: "" - loom: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # tag=v6.0.2 - with: - submodules: true - - name: Install stable - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # branch=master - with: - toolchain: stable - - name: cargo test --test loom - run: cargo test --release --test loom - env: - LOOM_MAX_PREEMPTIONS: 2 - RUSTFLAGS: "--cfg loom" + RUSTUP_TOOLCHAIN: ${{ env.NIGHTLY }} + # Loom permutation testing for concurrent code. Enable this job if the crate + # uses loom (https://crates.io/crates/loom) by uncommenting the lines below. + # loom: + # runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # tag=v6.0.2 + # with: + # submodules: true + # - name: Install stable + # uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # branch=master + # with: + # toolchain: stable + # - name: cargo test --test loom + # run: cargo test --release --test loom + # env: + # LOOM_MAX_PREEMPTIONS: 2 + # RUSTFLAGS: "--cfg loom" diff --git a/.github/workflows/scheduled.yml b/.github/workflows/scheduled.yml index 81a2910..a99453e 100644 --- a/.github/workflows/scheduled.yml +++ b/.github/workflows/scheduled.yml @@ -7,7 +7,7 @@ permissions: on: push: - branches: [main] + branches: [master] pull_request: schedule: - cron: '7 7 * * *' diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 0f0892d..244452c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,4 +1,4 @@ -# This is the main CI workflow that runs the test suite on all pushes to main and all pull requests. +# This is the master CI workflow that runs the test suite on all pushes to master and all pull requests. # It runs the following jobs: # - required: runs the test suite on ubuntu with stable and beta rust toolchains # - minimal: runs the test suite with the minimal versions of the dependencies that satisfy the @@ -12,7 +12,7 @@ permissions: on: push: - branches: [main] + branches: [master] pull_request: concurrency: @@ -161,8 +161,11 @@ jobs: - name: Record Rust version run: echo "RUST=$(rustc --version)" >> "$GITHUB_ENV" - name: Upload to codecov.io + if: env.CODECOV_TOKEN != '' uses: codecov/codecov-action@1af58845a975a7985b0beb0cbe6fbbb71a41dbad # tag=v5.5.3 with: fail_ci_if_error: true token: ${{ secrets.CODECOV_TOKEN }} env_vars: OS,RUST + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..eb2c02b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# Contributing Guidelines + +There are many ways to contribute. + +## Troubleshooting + +You can help other users in the community to solve their smart contract issues +in the [OpenZeppelin Forum]. + +[OpenZeppelin Forum]: https://forum.openzeppelin.com/ + +## Opening an issue + +You can [open an issue] to suggest a feature or report a minor bug. + +If you believe your issue may be due to user error and not a problem in the +library, consider instead posting a question on the [OpenZeppelin Forum]. + +Before opening an issue, be sure to search through the existing open and closed +issues, and consider posting a comment in one of those instead. + +When requesting a new feature, include as many details as you can, especially +around the use cases that motivate it. Features are prioritized according to +the impact they may have on the ecosystem, so we appreciate information showing +that the impact could be high. + +[open an issue]: https://github.com/OpenZeppelin/rust-project-template/issues/new/choose + +## Finding a proper issue + +### New Contributors + +If you're new and looking for a good place to start, check out issues labeled ["good first issue"]. + +["good first issue"]: https://github.com/OpenZeppelin/rust-project-template/issues?q=is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee + +## Submitting a pull request + +If you would like to contribute code or documentation you may do so by forking +the repository and submitting a pull request. + +Any non-trivial code contribution must be first discussed with the maintainers +in an issue (see [Opening an issue](#opening-an-issue)). Only very minor +changes are accepted without prior discussion. + +Make sure to read and follow the [engineering guidelines](./GUIDELINES.md). Run +linter and tests to make sure your pull request is good before submitting it. \ No newline at end of file diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..23864ef --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "rust-project-template" +version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 9989088..db7eb02 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,26 +1,20 @@ [package] -name = "{{project-slug}}" +name = "rust-project-template" version = "0.1.0" edition = "2024" authors = ["OpenZeppelin"] publish = true -description = "{{project-description}}" +description = "project description" +rust-version = "1.85.0" categories = [ # https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field ] keywords = [ # https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field ] -license = "{{license}}" -repository = "https://github.com/OpenZeppelin/{{project-slug}}" -exclude = [ - ".github/", - ".vscode/", - ".config/", - ".cargo/", - "benches/", - "tests/", -] +license = "MIT" +repository = "https://github.com/OpenZeppelin/rust-project-template" +exclude = [".github/", ".vscode/", ".config/", ".cargo/", "benches/", "tests/"] [dependencies] diff --git a/GUIDELINES.md b/GUIDELINES.md index 55790f0..10917e5 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -265,12 +265,12 @@ If you make documentation changes, you may want to check whether there are any warnings or errors: ```shell - cargo doc --all-features + RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps --all-features ``` ## Pull requests -Pull requests are squash-merged to keep the `main` branch history clean. The +Pull requests are squash-merged to keep the `master` branch history clean. The title of the pull request becomes the commit message, which should follow [Semantic versioning]. diff --git a/README.md b/README.md index 16984e6..183cbff 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ You can instantiate a new crate by using GitHub’s **“Use this template”** After creation: -- **Rename placeholders** in `Cargo.toml` and other files (see +- **Rename placeholders** in `Cargo.toml` and the repository docs/templates (see + [First-time setup checklist](#first-time-setup-checklist) and [File-by-file customization](#file-by-file-customization)). - **Decide your MSRV policy** and align it across `rust-toolchain.toml`, `Cargo.toml` (edition), and CI. @@ -29,11 +30,46 @@ After creation: ### 2) Clone and start coding -Typical dev loop: +## First-time setup checklist + +If this is your first time creating a repository from this template, use this +checklist before you start writing code: + +1. **Update crate/package metadata in `Cargo.toml`** + - Replace `name` with your crate name. + - Replace `description` with a real one-line summary. + - Replace `repository` with your repository URL. + - Replace `authors` with the actual maintainers, if you use that field. + - Replace `license` if you are not shipping MIT. +2. **Choose which license files to keep** + - Keep only the license file(s) that apply to your project. + - Make sure the `Cargo.toml` `license` field matches the files you ship. +3. **Replace organization/project-specific names and links** + - Search the repository for the template values and replace them with your + own project details. + - At minimum, search for: + - `rust-project-template` + - `OpenZeppelin` + - `openzeppelin` + - `0xNeshi` + - `project description` +4. **Update maintainer/contact information** + - Set the correct owners in `.github/CODEOWNERS`. + - Update security reporting instructions in `SECURITY.md`. + - Update support/community links in GitHub issue templates if you use them. +5. **Review CI and toolchain policy** + - Set your MSRV in workflow files. + - Confirm `edition` is compatible with your MSRV. + - Decide whether `rust-toolchain.toml` should stay pinned. +6. **Trim anything you do not use** + - Remove workflows you do not need (`nostd.yml`, `safety.yml`, etc.). + - Remove example/bench scaffolding if it is not useful for your crate. + +After the checklist, run a sanity check: ```bash cargo test --all-features --all-targets -cargo fmt +cargo +nightly fmt --check cargo clippy --all-features --all-targets ``` @@ -77,8 +113,9 @@ you should **make these consistent** for your crate. ## File-by-file customization -This section is intentionally brief: it’s a checklist of what you should update -when you create a new project from this template. +This section is a concrete map of which files usually need project-specific +names, links, maintainers, and policy choices changed after you create a new +repository from this template. ### `Cargo.toml` @@ -88,6 +125,7 @@ when you create a new project from this template. - `repository` - `license` - `authors` (if applicable) + - `keywords` and `categories` once you know how you want to publish the crate - **Review**: - `edition` (must align with your MSRV) - `lints.*` (tune warning levels for your team) @@ -115,6 +153,7 @@ when you create a new project from this template. - Tests on stable/beta, minimal dependency versions, OS matrix, coverage. - `scheduled.yml`: - Nightly “rolling” checks and “updated dependencies” checks. + - Review repository-specific job names, notifications, and assumptions. - `safety.yml`: - Optional deeper checks (sanitizers, Miri, Loom). Remove if irrelevant. - Note: this workflow installs system packages; keep only if you want it. @@ -129,20 +168,21 @@ when you create a new project from this template. ### `.github/CODEOWNERS` -- Replace `{{code-owner}}` placeholders with the correct GitHub handles/teams. +- Add correct GitHub handles/teams. - Ensure `SECURITY.md` has the right owners. ### `.github/ISSUE_TEMPLATE/*` and `.github/pull_request_template.md` - Adjust wording to your project. -- Consider adding a PR checklist item that ensures the license is not a - placeholder (if you use placeholder licenses). +- Replace support links, repository links, and organization names. ### `rustfmt.toml` and `clippy.toml` - Tune formatting and clippy settings to team preferences. - `rustfmt.toml` includes settings that may require nightly rustfmt depending on your toolchain; adjust if you need strict stable-only formatting. +- `clippy.toml` may include organization-specific identifiers; review + `doc-valid-idents`. ### `codecov.yml` and `.github/codecov.yml` @@ -156,12 +196,15 @@ when you create a new project from this template. ### `SECURITY.md` -- Update project name/slug placeholders. -- Ensure the reporting mechanism and links point to your repository. +- Update the project name, organization name, and repository slug. +- Replace the vulnerability reporting contact/channel with your own. +- Ensure the advisory submission link points to your repository. +- Review any legal text inherited from the template owner. ### `CODE_OF_CONDUCT.md` - Keep as-is, or replace with your organization’s standard CoC. +- If you keep this file, review the enforcement/reporting contact details. ### `CONTRIBUTING.md` @@ -174,6 +217,7 @@ when you create a new project from this template. - Choose the license(s) that apply to your project. - Ensure `Cargo.toml` `license = "..."` matches what you ship. - Remove any licenses you do not intend to ship. +- If your chosen license requires copyright holder updates, make those changes. ### `src/lib.rs` @@ -187,6 +231,19 @@ when you create a new project from this template. - E.g. configures cargo formatter to always run in `nightly` to access latest formatting features. - Keep, adjust, or remove. +## Recommended repository-wide search + +Before your first release, do one repository-wide search for template values and +verify each remaining match is intentional. + +Suggested search terms: + +- `rust-project-template` +- `OpenZeppelin` +- `openzeppelin` +- `0xNeshi` +- `project description` + ## Notes for existing projects You can also use this repository as a **reference checklist** for existing Rust diff --git a/SECURITY.md b/SECURITY.md index f04974d..276f0f0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -21,7 +21,7 @@ We're extremely grateful for security researchers and users that report vulnerab All reports are thoroughly investigated by the project's security team. Vulnerabilities are reported privately via GitHub's [Security Advisories](https://docs.github.com/en/code-security/security-advisories) feature. -Please use the following link to submit your vulnerability: [Report a vulnerability](https://github.com/openzeppelin/{{project-slug}}/security/advisories/new) +Please use the following link to submit your vulnerability: [Report a vulnerability](https://github.com/openzeppelin/rust-project-template/security/advisories/new) Please see [Privately reporting a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability) @@ -29,7 +29,7 @@ for more information on how to submit a vulnerability using GitHub's interface. ## Legal -OpenZeppelin {{project-name}} is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin {{project-name}} and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project. +OpenZeppelin rust-project-template is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin rust-project-template and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project. ## Audits diff --git a/benches/bench_1.rs b/benches/bench_1.rs index e69de29..a54b72d 100644 --- a/benches/bench_1.rs +++ b/benches/bench_1.rs @@ -0,0 +1 @@ +#![allow(missing_docs)] diff --git a/examples/example_1.rs b/examples/example_1.rs index e69de29..77ecec0 100644 --- a/examples/example_1.rs +++ b/examples/example_1.rs @@ -0,0 +1,3 @@ +#![allow(missing_docs)] + +fn main() {} diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 4f3e8c5..c1bc0a6 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,2 +1,2 @@ [toolchain] -channel = "1.89" +channel = "1.85.0" diff --git a/src/lib.rs b/src/lib.rs index b93cf3f..ca644c3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,7 @@ +//! Module-level documentation. + +/// Documentation comments. +#[must_use] pub fn add(left: u64, right: u64) -> u64 { left + right }