Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
167 lines (125 loc) · 6.91 KB

CONTRIBUTING.md

File metadata and controls

167 lines (125 loc) · 6.91 KB

Contributing

Bug reports and pull requests are welcome on GitLab at https://gitlab.com/appraisal-rb/appraisal2 . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

To submit a patch, please fork the project and create a patch with tests. Once you're happy with it send a pull request.

Remember to Keep A Changelog if you make changes.

You can help!

Simply follow these instructions:

  1. Join the Discord: Live Chat on Discord
  2. Fork the repository
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Make some fixes.
  5. Commit your changes (git commit -am 'Added some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. Make sure to add tests for it. This is important, so it doesn't break in a future release.
  8. Run the at least one workflow of tests via act, e.g.,: 
    act -W '.github/workflows/ruby-3-3.yml'
    NOTE: Because there are so many workflows, running act naked might grind your machine to a halt.
  9. Create new Pull Request.
  10. Announce it in the channel for this org in the Discord!

NOTE: Run tests with act to have confidence they will pass in CI. Also, because the spec run makes many changes to local bundle config, many specs will fail locally in subsequent runs unless run via act. The spec suite is not idempotent. This is a goal for the future, if you'd like to work on it.

Appraisals

From time to time the appraisal2 gemfiles in gemfiles/ will need to be updated. They are created and updated with the commands:

bin/rake appraisal:update

If you need to reset all gemfiles/*.gemfile.lock files:

bin/rake appraisal:reset

When adding an appraisal to CI, check the runner tool cache to see which runner to use.

The Reek List

Take a look at the reek list which is the file called REEK and find something to improve.

To refresh the reek list:

bundle exec reek > REEK

Run Tests

To run all tests against the current Ruby release:

bundle exec rake act

Or the equivalent:

act -W '.github/workflows/current.yml'

NOTE: Because there are so many workflows, running act naked might grind your machine to a halt.

Lint It

Run all the default tasks, which includes running the gradually autocorrecting linter, rubocop-gradual.

bundle exec rake

Or just run the linter.

bundle exec rake rubocop_gradual:autocorrect

Contributors

Your picture could be here!

Contributors

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/appraisal-rb/appraisal2/-/graphs/main

For Maintainers

One-time, Per-maintainer, Setup

IMPORTANT: To sign a build, a public key for signing gems will need to be picked up by the line in the gemspec defining the spec.cert_chain (check the relevant ENV variables there). All releases are signed releases. See: RubyGems Security Guide

NOTE: To build without signing the gem you must set SKIP_GEM_SIGNING to some value in your environment.

To release a new version:

Automated process

  1. Update version.rb to contain the correct version-to-be-released.
  2. Run bundle exec kettle-changelog.
  3. Run bundle exec kettle-release.
  4. Stay awake and monitor the release process for any errors, and answer any prompts.

Manual process

  1. Run bin/setup && bin/rake as a "test, coverage, & linting" sanity check
  2. Update the version number in version.rb, and ensure CHANGELOG.md reflects changes
  3. Run bin/setup && bin/rake again as a secondary check, and to update Gemfile.lock
  4. Run git commit -am "🔖 Prepare release v<VERSION>" to commit the changes
  5. Run git push to trigger the final CI pipeline before release, and merge PRs
  6. Run export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME
  7. Run git checkout $GIT_TRUNK_BRANCH_NAME
  8. Run git pull origin $GIT_TRUNK_BRANCH_NAME to ensure latest trunk code
  9. Optional for older Bundler (< 2.7.0): Set SOURCE_DATE_EPOCH so rake build and rake release use the same timestamp and generate the same checksums
    • If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default.
    • Run export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH
    • If the echo above has no output, then it didn't work.
    • Note: zsh/datetime module is needed, if running zsh.
    • In older versions of bash you can use date +%s instead, i.e. export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH
  10. Run bundle exec rake build
  11. Run bin/gem_checksums (more context 1, 2) to create SHA-256 and SHA-512 checksums. This functionality is provided by the stone_checksums gem.
    • The script automatically commits but does not push the checksums
  12. Sanity check the SHA256, comparing with the output from the bin/gem_checksums command:
    • sha256sum pkg/<gem name>-<version>.gem
  13. Run bundle exec rake release which will create a git tag for the version, push git commits and tags, and push the .gem file to the gem host configured in the gemspec.
⚡