How we create and release new open source projects at Embark.
Setup New Repo
- Pick a name that isn't used on crates.io, also an emoji
- Do the usual repo creation under the Embark org with the same name as the crate(s)
- Clone down the repo or else set it as the remote for an existing repo
inityour repo if needed
- Do a
cargo packageand fixup any issues, normally this is stuff like missing the repository/docs/homepage etc metadata fields
- Do an initial publish of the crate with
cargo publish --token <TOKEN>where
TOKENis and API token for the
embark-studiosuser. This shared bot account allows us to publish all crates under the same user and not have to worry about managing owners.
We mainly use Travis CI for all of our public code, but the general steps here would apply to whatever CI a repo decides to use.
It's recommended you use our Open Source Template when creating a new Rust Github repo, this already contains some basic CI templates and scripts to bootstrap your setup.
If you don't use the template, you can copy one of our existing repos that most closely matches your new repo.
The rest of this guide assumes you are using the CI setup from the Open Source Template.
.travis.yml. We don't actually run real CI on our template repo!
Add/remove steps as makes sense for the project
- As noted in our guidelines, we expect all our code to follow default rustfmt, and not have clippy
warnings, so have at least 1 lint step that checks these on the
stablechannel, and it's recommended to have one that does the same thing on the
betachannel as well as new clippy lints can trigger failures in the next
- Have a
stabletest for all the platforms we support, which is usually
- Probably want to have at least 1 test that runs using the
nightlychannel, it's recommended to use
linuxfor this as the VM spinup, rust install, compilation, and test runs are generally all faster on linux machines than the other platforms, particularly Windows
- As noted in our guidelines, we expect all our code to follow default rustfmt, and not have clippy warnings, so have at least 1 lint step that checks these on the
Add a deploy step
- Add a separate deploy stage that only runs on semver tags
stages: - test - name: deploy if: tag =~ /^\d+\.\d+\.\d+.*$/
- If a lib/bin project, add a deploy step for publishing to crates.io
- stage: deploy rust: stable os: linux script: echo "deploying $TRAVIS_TAG to crates.io" deploy: provider: cargo token: secure: <SEKRETZ> on: repo: EmbarkStudios/your-repo-name tags: true
You should get an crates.io API token from Johan for the
embark-studiosGithub bot we have, but Once you have the API token, you need to encrypt it, which you can do with travis-cli tool
travis encrypt <token>. Then just copy and paste the token into the
- If a bin project, copy what cargo-deny does, including all of the scripts. This will generate .tar.gz archives for all target platforms and upload them to Github releases so that people can install the binary without having to install Rust if that is their desire.
Push your travis config and see how it goes!
Publishing New Versions
Given the above setup is followed correctly, publishing turns into a fairly trivial exercise.
- Change the
versionin Cargo.toml and commit
- Tag the commit
git tag -a <version> -m "Release <version>". Example:
git tag -a 0.1.0 -m "Release 0.1.0"
- Push the commit(s) and tag so that the release will be published automatically
git push --follow-tags