Skip to content

Latest commit

 

History

History
227 lines (168 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

227 lines (168 loc) · 6.95 KB
Raw

Contributing to Artichoke – raw-parts

👋 Hi and welcome to Artichoke. Thanks for taking the time to contribute! 💪💎🙌

Artichoke aspires to be a recent MRI Ruby-compatible implementation of the Ruby programming language. There is lots to do.

raw-parts is a utility crate that makes Vec::from_raw_parts and Vec::into_raw_parts APIs easier to use by giving names to the raw parts. Artichoke uses this crate in its implementations of Array and String.

If Artichoke does not run Ruby source code in the same way that MRI does, it is a bug and we would appreciate if you filed an issue so we can fix it. File bugs specific to raw-parts in this repository.

If you would like to contribute code to raw-parts 👩‍💻👨‍💻, find an issue that looks interesting and leave a comment that you're beginning to investigate. If there is no issue, please file one before beginning to work on a PR. Good first issues are labeled E-easy.

Discussion

If you'd like to engage in a discussion outside of GitHub, you can join Artichoke's public Discord server.

Setup

raw-parts includes Rust, Ruby, and Text sources. Developing on raw-parts requires configuring several dependencies.

Rust Toolchain

raw-parts depends on Rust and several compiler plugins for linting and formatting. raw-parts is guaranteed to build on the latest stable release of the Rust compiler.

Installation

The recommended way to install the Rust toolchain is with rustup. On macOS, you can install rustup with Homebrew:

brew install rustup-init
rustup-init

Once you have rustup, you can install the Rust toolchain needed to compile raw-parts:

rustup toolchain install stable
rustup component add rustfmt
rustup component add clippy

To update your stable Rust compiler to the latest version, run:

rustup update stable

Rust Crates

raw-parts depends on several Rust libraries, or crates. Once you have the Rust toolchain installed, you can install the crates specified in Cargo.toml by running:

cargo build

Ruby

raw-parts requires a recent Ruby and bundler for development tasks. The .ruby-version file in this repository specifies the preferred Ruby toolchain.

If you use RVM, you can install Ruby dependencies by running:

rvm install "$(cat .ruby-version)"
gem install bundler

If you use rbenv and ruby-build, you can install Ruby dependencies by running:

rbenv install "$(cat .ruby-version)"
gem install bundler
rbenv rehash

The Gemfile in this repository specifies several dev dependencies. You can install these dependencies by running:

bundle install

raw-parts uses rake as a task runner. You can see the available tasks by running:

$ bundle exec rake --tasks
rake build                        # Build Rust workspace
rake bundle:audit:check           # Checks the Gemfile.lock for insecure dependencies
rake bundle:audit:update          # Updates the bundler-audit vulnerability database
rake doc                          # Generate Rust API documentation
rake doc:open                     # Generate Rust API documentation and open it in a web browser
rake fmt                          # Format sources
rake fmt:rust                     # Format Rust sources with rustfmt
rake fmt:text                     # Format text, YAML, and Markdown sources with prettier
rake format                       # Format sources
rake format:rust                  # Format Rust sources with rustfmt
rake format:text                  # Format text, YAML, and Markdown sources with prettier
rake lint                         # Lint sources
rake lint:clippy                  # Lint Rust sources with Clippy
rake lint:clippy:restriction      # Lint Rust sources with Clippy restriction pass (unenforced lints)
rake lint:rubocop                 # Run RuboCop
rake lint:rubocop:autocorrect     # Auto-correct RuboCop offenses
rake release:markdown_link_check  # Check for broken links in markdown files
rake test                         # Run raw-parts unit tests
rake unicode:build                # Rebuild Rust generated Rust sources from Unicode data
rake unicode:update               # Update Unicode data

To lint Ruby sources, raw-parts uses RuboCop. RuboCop runs as part of the lint task. To run RuboCop by itself, invoke the lint:rubocop task.

$ bundle exec rake lint
$ bundle exec rake lint:rubocop

Node.js

Node.js is an optional dependency that is used for formatting text sources with prettier.

Node.js is only required for formatting if modifying the following filetypes:

  • md
  • yaml
  • yml

You will need to install Node.js.

On macOS, you can install Node.js with Homebrew:

brew install node

Linting

To lint and format all sources run:

rake lint

Testing

A PR must have new or existing tests for it to be merged. The Rust book chapter on testing is a good place to start.

To run tests:

cargo test

cargo test accepts a filter argument that will limit test execution to tests that substring match. For example, to run all of the tests for ascii casecmp:

cargo test ascii

Tests are run for every PR. All builds must pass before merging a PR.

Updating Dependencies

Rust Crates

Version specifiers in Cargo.toml are NPM caret-style by default. A version specifier of 4.1.2 means 4.1.2 <= version < 5.0.0.

To see what crates are outdated, you can use cargo-outdated.

If you need to pull in an updated version of a crate for a bugfix or a new feature, update the version number in Cargo.toml. See artichoke/artichoke#548 for an example.

Regular dependency bumps are handled by @dependabot.