Note
This template is primary designed for myself.
A repository template for Rust-based applications and libraries.
This repository serves as a template for creating new Rust application and library repositories. The template is pre-configured to be used within a development container, providing a consistent development environment for contributors. Customizations are included for Visual Studio Code that should make Rust development nicer.
There are two stages to getting started: making this repository yours, and using Visual Studio Code for development. If you do not intend to use Visual Studio Code, you can skip that section. If you also do not intend to use development containers, you can delete the .devcontainer/
folder.
-
Clone this repository.
Obviously, we are not going to make changes to the original template.
-
Modify
Cargo.toml
.Most of the metadata contains placeholder values that should be replaced.
-
Modify
.github/workflows/test.yml
.One of the jobs may need to be deleted, and the other modified to better support the project. Consider configuring the
dtolnay/rust-toolchain
action to use a specific version of Rust. -
Modify
.gitignore
to allowCargo.lock
.If appropriate, you may want to uncomment the line that allows
Cargo.lock
to be included in the repository. It is best practice to include this for binaries, but not for libraries. -
Replace
README.md
.The original README in the template is meant as a guide on how to use it, so a new README for the project is needed. For some inspiration, check out Awesome README which provides a curated listed of... awesome READMEs!
-
Replace GitHub issue labels.
The issue templates make use of three specific labels: Bug, Enhancement, and Feature. It is recommended to also include labels for Duplicate, Invalid, and Won't Fix. The following table may be copied and pasted from when setting up issue labels:
Label Description Color Bug Identification of, or the solution to, a bug. #ee3f46
Duplicate A duplicate issue or solution. #d2dae1
Enhancement Identification of, or the solution to, an enhancement to an existing feature. #5ebeff
Feature Proposal of, or work done for, a new feature. #91ca55
Invalid An incorrect, misidentified, or out of scope issue or solution. #d2dae1
Won't Fix An issue or solution for something working as intended or is out of scope. #d2dae1
-
Install Docker Desktop.
This is needed to build and run the containerized development environment.
-
Install Visual Studio Code.
Along with the IDE, we also want to be sure that the Dev Containers extension is installed in order to more easily build, launch, and interact with the container.
-
Open the cloned repository folder.
When the folder is opened, Visual Studio Code will ask if you would like to re-open the project in a container. Answer the prompt in the affirmative and the container should automatically build, launch, and be accessed by the IDE.
-
Check for open issues.
Before submitting any pull requests, an issue must first exist to associate the PR to. If a relevant issue cannot be found, please feel free to open a new one. A form will be presented depending on the type of issue encountered.
-
Open a pull request.
Once you have created or found an issue, create a fork with the desired changes and open a pull request. Please follow the instructions in the PR templates carefully, otherwise I may close it.
The full continuous integration test suite may be run locally.
./scripts/test.sh
This template is made available under the ISC license.
While the license does stipulate that a copyright notice be included in your project, I have no desire to enforce this. I would choose a better license, but I am not aware of any that would have the same stipulations as the ISC license without that particular clause.
Hopefully, your project is a success (personally or commercially)!