Contribution Guide#

I appreciate your interest in contributing to our project! 😍

All contributions are welcome. This document aims to provide information on the development process, such as local development, commit, pull request, continuous integration, release, and more.

To start contributing, feel free to fork the repository.

Branch Organization and Release Strategy#

We use the main branch for development and CI. We release them with semantic versioning as tags. The release tag is per Rust crate, and the crate version is the same as the tag name.

Setup local development environment#

For now, this documentation aims to develop the project on Windows. However, the Rust language and the tools in the project are cross-platform. So you can grow it on other platforms like Linux and macOS.

Prerequisites#

You might not need to install Rust and Node.js using the proto mentioned in the "Optional Development Tools" section below.

• Git
• Rust
• Node.js (for documentation development)
• Any text editor or IDE you like

Optional Development Tools#

I recommend the following development tools. The instructions in this "Setup local development environment" section assume you have installed these tools.

You can skip the following tools if you are familiar with Rust, Cargo, Node.js, and npm. Each development task, like build, test, etc., is defined in the moon.yml file. (For Rust crates <project-root>/moon.yml file, for documentation <project-root>/doc/moon.yml) Feel free to explore the file and run the commands directly.

• proto: Version manager for Rust, Node.js, and other tools
• moon: Task runner and repository management tool

*If you see an error message like "command not found" when you run the command in the following procedure, try to restart the terminal or PowerShell.

Setup proto#

Reference: Install proto

First, run the following command in PowerShell to install the proto.

irm https://moonrepo.dev/install/proto.ps1 | iex

Then, set the execution policy to run the script.

Set-ExecutionPolicy RemoteSigned

# Without admin privileges
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Install Rust, Node.js, and other tools#

In the project root directory, run the following command.

proto use

*If you see an error, try to execute the proto install <tool> command for each tool.

Run the first command with the moon#

Before running the moon command, let's set up the toolchain configuration file, Rust components, and bins (Rust binary executables). Open the <project-root>/.moon/toolchain.yml file and turn on the following lines. (components and bins sections)

1# https://moonrepo.dev/docs/config/toolchain
2# yaml-language-server: $schema=https://moonrepo.dev/schemas/toolchain.json
3
4node:
5  packageManager: 'yarn'
6
7rust:
8  syncToolchainConfig: true
9  components:
10    - 'rustfmt'
11    - 'clippy'
12  bins:
13    - bin: 'cargo-nextest'
14      local: true
15    - bin: 'release-plz'
16      local: true
17    - bin: 'cargo-license'
18      local: true
19    - bin: 'cargo-about'
20      local: true
21    - bin: 'kickstart'
22      local: true
23    - bin: 'adrs'
24      local: true
25  # targets:
26  #   - 'x86_64-pc-windows-gnu'
27  #   - 'x86_64-unknown-linux-gnu'

Then save the file and run the following command.

moon uobors:test

This command will install the Rust components/bins and run the unit test for the Rust crates. It might take some minutes to build the dependencies so that you can take a coffee break ☕️.

After the command finishes, you might see the test results in the terminal.

Once you have completed the above steps, you can turn off the components and bins sections in the <project-root>/.moon/toolchain.yml file. You can turn on them when you need to update the toolchain configuration. (The repository's default configuration is to turn off the components and bins sections)

And that's it! You are ready to develop the project 😄.

Task Commands#

The moon command is a task runner and repository management tool. The command syntax is moon <project-name>:<task-name>.

We have two projects in this repository: uobors and uobors-doc. The <project-root>/.moon/workspace.yml file defines the projects.

The task commands definition is in the <project-root>/moon.yml file for the Rust crates and the <project-root>/doc/moon.yml file for the documentation site. See those files for complete information on the task commands.

For Rust code checking and testing#

• Run the linter (clippy) for the Rust crates

moon uobors:lint

• Run the formatter (rustfmt) for the Rust crates

moon uobors:format

• Run the unit test using the nextest for the Rust crates

moon uobors:test

• Run the doc test for the Rust crates

moon uobors:doctest

• Run the above four commands and check the Rust crates using the cargo check command

moon uobors:check

• Run the uobors_cli crate with the cargo run command

moon uobors:run-cli -- <args>

• Run the crates in the <project-root>/examples directory with the cargo run command

moon uobors:example -- <example-name>

• Build the Rust crates with the debug profile

moon uobors:debug-build

• Build the Rust crates with the release profile

moon uobors:release-build

*When running the debug and release build commands, run the linter, formatter, unit test, and doc test before building.

For Rust crate documentation generation#

• Generate the documentation for the Rust crates

moon uobors:doc

If you want to open the generated documentation in the browser, run the following command.

moon uobors:doc --open

• Generate the uobors_cli command help document

moon uobors:cli-help-doc

This command generates the uobors_cli command help document in the <project-root>/doc/docs/en directory.

For License documentation#

• View the license information of the dependencies

moon uobors:license-list

• Generate the license HTML file of the dependencies

moon uobors:license-html

Other commands for the Rust crates#

• Clean the target directory of the Rust crates

moon uobors:clean

• Update the Rust crates' dependencies

moon uobors:update-deps

For documentation site development#

• Install the dependencies for the documentation site development

moon uobors-doc:install

• Start the documentation development server

moon uobors-doc:dev

• Start the static site server for the documentation

moon uobors-doc:preview

• Build the documentation site

moon uobors-doc:build

Conventional Commits and CHANGELOG.md#

We use the Conventional Commits specification for commit messages. The commit message format is <type>[optional scope]: <description>. The type list is in the <project-root>/release-plz.toml file. (commit_parsers section)

We automatically generate the CHANGELOG.md file from the commit messages using the release-plz crate and GitHub Action that appears in the following section. The release-plz GitHub Action will modify the CHANGELOG.md file, including the release notes generated from the commit messages.

When you make a pull request, we would appreciate it if you would follow the Conventional Commits specification for the commit messages.

Pull Request (Change PR)#

(TODO: Make a PR template)

Continuous Integration (CI)#

CI workflow will run the tests and debug-build the project when we push a new commit or create a pull request to the main branch, but only if the Rust source code is changed. See details in the <project-root>/.github/workflows/ci.yml file.

At the same time, another workflow checks the licenses and tries to generate the aggregated license HTML file of the dependencies. It works with the cargo-about crate. See details in the <project-root>/.github/workflows/license_check.yml file. The <project-root>/about.toml file is the configuration file for the cargo-about tool.

Release PR and Rust crate release#

Furthermore, when Rust source code changes, we automatically create a release pull request (release PR) for the next release. It works with the release_plz create and GitHub Action. See details in the <project-root>/.github/workflows/release_plz.yml file. The <project-root>/release-plz.toml file is the configuration file for the release-plz tool.

Release PR also includes the CHANGELOG.md file generated from the commit messages. The release-plz creates the release PR's source branch separately from the main branch. Therefore, you can do it in the release PR's source branch if you want to change the CHANGELOG.md file or the crates' version.

When we merge the release PR into the main branch, the release-plz workflow will create a new tag, release the Rust crates to crates.io, and make the release to GitHub. At that time, if the uobors_cli crate is updated, the CLI release workflow will release-build the CLI and upload the zip archive file, including binary, to the GitHub release page. This zip archive includes the license files and the templates directory. See details in the <project-root>/.github/workflows/uobors_cli_release.yml file.

Documentation release#

The documentation is automatically built and published in GitHub Pages when we push a new commit or merge a pull request to the main branch, but only if the documentation directory (<project-root>/doc) or <project-root>/.github/CONTRIBUTING.md is changed. See details in the <project-root>/.github/workflows/doc_release.yml file.

This documentation is written in Markdown and MDX format and built with Rspress. For more about documentation authoring, see the link. But it's almost simple Markdown syntax. I think authoring is not so difficult. (Except for the English learners like me 😓. This document heavily depends on GitHub Copilot and Grammarly!)

The Architecture Decision Records (ADRs)#

We use Architecture Decision Records (ADRs) to document architectural decisions. See What is an Architecture Decision Record? for more information.

License#

By contributing to this project, you agree that your contributions' license is under its LICENSE. This project's license is under the MIT license. See the LICENSE file for the license terms.

Furthermore, the sprite and sound assets in the template directory, its license are under the CC0 license. See the SPRITE-AND-SOUND-LICENSE file for the license terms.