Skip to content

Latest commit

 

History

History
204 lines (144 loc) · 6.36 KB

CONTRIBUTING.md

File metadata and controls

204 lines (144 loc) · 6.36 KB

Contributing to Artichoke

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

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

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.

If you would like to contribute code 👩‍💻👨‍💻, 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.

Implementation Philosophy

Setup

Artichoke includes Rust, Ruby, C, and Text sources. Developing on Artichoke requires configuring several dependencies.

Rust Toolchain

Artichoke depends on Rust and several compiler plugins for linting and formatting. The specific version of Rust that Artichoke requires is specified in the toolchain file.

Toolchain requirements are documented in BUILD.md.

C Toolchain

Some Artichoke dependencies, like the mruby sys module and the onig crate, build C static libraries and require a C compiler.

Toolchain requirements are documented in BUILD.md.

Ruby

Artichoke requires a recent Ruby 2.x and bundler 2.x. The .ruby-version file in this repository specifies Ruby 2.6.3.

Toolchain requirements are documented in BUILD.md.

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

$ bundle exec rake --tasks
rake doc               # Generate Rust API documentation
rake doc:open          # Generate Rust API documentation and open it in a web browser
rake lint:all          # Lint and format
rake lint:clippy       # Run clippy
rake lint:deps         # Install linting dependencies
rake lint:eslint       # Run eslint
rake lint:format       # Format sources
rake lint:links        # Check markdown links
rake lint:restriction  # Lint with restriction pass (unenforced lints)
rake lint:rubocop      # Run rubocop
rake spec              # Run enforced ruby/spec suite
rake test              # Run Artichoke Rust tests

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

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:

  • c
  • h
  • html
  • json
  • md
  • toml
  • yaml
  • yml

You will need to install Node.js.

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

brew install node

Node.js Packages

Once you have Node.js installed, you can install the packages specified in package.json.

Node.js packages are automatically installed by linting tasks defined in the Rakefile.

Code Quality

Linting

Once you configure a development environment, run the following to lint sources:

rake lint:all

Merges will be blocked by CI if there are lint errors.

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. If you'd like to see some examples in Artichoke, take a look at the Value tests in artichoke-backend/src/value/mod.rs.

To run tests:

rake test

If you are only working on one crate, it can speed up iteration time to only build and run tests for that crate:

cargo test -p artichoke-backend

cargo test accepts a filter argument that will limit test execution to tests that substring match. For example, to run all of the Ruby/Rust interop tests:

cargo test -p artichoke-backend convert

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

Updating Dependencies

Rust Toolchain

Upgrades to the Rust toolchain should happen in a dedicated PR that addresses any changes to ructc warnings and clippy lints. See GH-482 for an example.

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 GH-548 for an example.

To update Rust crate dependencies run the following command and check in the updated Cargo.lock file:

cargo update

Node.js Packages

To see what packages are outdated, you can run npm outdated.

To update Node.js package dependencies run the following command and check in the updated package-lock.json file:

npm update

If after running npm update there are still outdated packages reported by npm outdated, there has likely been a major release of a dependency. If you would like to update the dependency and deal with any breakage, please do; otherwise, please file an issue.