Check out our GitHub!

orogene

Contributing to orogene

Finding Something to Do

Orogene has a roadmap and welcomes contributions! Issues looking for outside help are tagged as help wanted. On top of that, there are good first issue for those looking to get started more entry-level tasks.

Coding Conventions

Orogene uses conventional commits as its commit message format. Ideally, any pull requests will already use this style when submitting, but commit messages will simply be editorialized on merge if not, so consider this a soft request.

This repo uses both clippy and rustfmt to maintain consistency. Before submitting a pull request, please make sure to run both cargo clippy --all and cargo fmt --all.

Getting up and running

Orogene is a pretty run-of-the-mill Rust app and only requires a couple of steps to get up and running.

Build Dependencies

You will need git in order to fetch the orogene sources. Next, to get a checkout:

git clone https://github.com/orogene/orogene.git
cd orogene

Additionally, some tools are required to compile/build orogene:

  1. (Linux only) An available OpenSSL installation: https://docs.rs/openssl/latest/openssl/#automatic
  2. Cargo, which can be installed using rustup
  3. Clippy, which is a component that should be added through rustup.

orogene is built against relatively recent stable versions of Rust. For a specific version to install, refer to Cargo.toml's [package] section, as rust-version.

If you plan on builing wasm packages for orogene sub-crates, you'll also need:

  1. cargo install -f wasm-bindgen-cli
  2. cargo install -f wasm-pack (or installed prebuilt binaries)

Building the CLI

Linux has a couple of build requirements. These can be installed on ubuntu with the following command. Adapt as needed for your distro:

sudo apt-get install build-essential pkg-config libssl-dev

On Windows, you'll need a working msvc.

You can build the CLI using a plain cargo build (optionally with --release), and binaries will be available in your local ./target/{debug,release}/oro[.exe] directory.

The oro/oro.exe is a standalone binary but, on Linux, does require a valid installation of openssl 1 installed on the system in order to run.

Building WASM packages

There's currently two packages with support for WASM, only one of which should really be used right now: crates/nassun and crates/node-maintainer. Both of them are published to the NPM registry as part of orogene's release process.

node-maintainer is orogene's dependency resolver and is responsible for calculating dependency trees based on package.json, lockfiles, etc. Extraction to filesystems is not supported in WASM mode because it is built for wasm32-unknown-unknown, not wasm-wasi. node-maintainer also exports nassun's APIs under the same wasm package, so it's not recommended to install both nassun and node-maintainer wasm packages.

To build node-maintainer:

  1. Make sure you're in the orogene project root.
  2. wasm-pack build crates/node-maintainer --target web
  3. There will now be an NPM package under crates/node-maintainer/pkg that can be packed, copied (to vendor it somewhere, etc).

Working on the installer

Orogene's "install" command is called apply. During development, you can call it like this:

$ cargo run [--release] -- apply [--root ../path/to/test/react-app] [--oro-cache ./path/to/cache] [--loglevel info]

It might be worth it to run with --release every time if you plan on seeing applies to completion, because debug builds of orogene are pretty slow.

The apply command itself is defined in src/commands/apply.rs, and is pretty much a UI wrapper around crates/node-maintainer's APIs.

If you're only interested in the dependency resolution aspect of apply, you can run with --lockfile-only, which will skip the much more expensive extraction process.

Logging

orogene uses tracing and tracing-subscriber for tracing and logging capabilities, which can be configured through --loglevel. The syntax for this option is documented here. For example, cargo run -- apply --loglevel node_maintainer=trace,info will default to INFO-level logging for everything, but also include TRACE-level logging for anything logged by node-maintainer (node the underscore. It's based on the module name, not the crate.)

Tagging and Releasing New Versions

Releasing orogene is a four-step process:

  1. First, we make sure all the READMEs are up-to-date.
  2. Then, a changelog is generated, editorialized, and commited.
  3. After that, a command is run to release the entire repository in lockstep.
  4. Finally, an automated process takes care of generating a GitHub release and building prebuilt binaries for distribution.

In order to follow these steps, you'll need to intall cargo-make:

$ cargo install -f cargo-make

Generate/Update READMEs

First, make sure crates/README.md is up-to-date with the latest crates available under crates/, in case any of them have been added, removed, or had significant description changes.

$ cargo make readmes

This command will update and/or update crate READMEs based on rustdoc from their main modules.

If there were any changes, add and commit them with git add and git commit -m 'docs: update READMEs'

Changelog

$ cargo make changelog X.Y.Z

Where X.Y.Z is the full target semver version of the intended upcoming release.

This will automatically update CHANGELOG.md with commits based on conventional-commits in the git log.

If any additional messages are to be included, please add them under the new version header.

git add CHANGELOG.md and git commit -m 'docs: update changelog' to complete this step.

Tag and Release

First, do a quick dry run:

$ cargo make release X.Y.Z

If everything looks good, execute it for real. You'll need to make sure you're logged into both GitHub and crates.io and allowed to publish and push to GitHub main:

$ cargo make release X.Y.Z --execute

This will take care of publishing all the crates in the repository under version X.Y.Z to crates.io, tagging a new git tag, and pushing everything to GitHub when it's done.

GitHub Release

orogene uses cargo-dist for generating prebuilt binaries and GitHub Releases. No intervention is necessary here. This is handled by a GitHub Action configured under .github/workflows/release.yml.

It may take some time for everything to build, but the final release will be made available under https://github.com/orogene/orogene/releases/tag/vX.Y.Z, at which point the new version may be announced.