Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (99 loc) · 6.77 KB

CONTRIBUTING.md

File metadata and controls

137 lines (99 loc) · 6.77 KB

Contributing

Any contribution is welcome.
Please read the CycloneDX contributing guidelines first.

Pull-requests from forks are welcome.
We love to see your purposed changes, but we also like to discuss things first. Please open a ticket and explain your intended changes to the community. And don't forget to mention that discussion in your pull-request later. Find the needed basics here:

Setup

This project uses ruby. Have a recent version installed and setup first.

To install dev-dependencies and tools:

bin/setup

Environment Variables for Local Development

Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.

General/runtime

  • MIMIC_NEXT_MAJOR_VERSION: When set to true, simulates the next major version for testing breaking changes 📌semver-breaking 📌major-versions-not-sacred (default: false)
  • ARUBA_NO_COVERAGE: Disable SimpleCov coverage in Aruba tests (default: false)

For a quick starting point, this repository’s .envrc shows sane defaults, and .env.local can override them locally.

Testing

To run all tests

bundle exec rake test

Or use the default task, which does the same

bundle exec rake

Spec organization (required)

  • One spec file per class/module. For each class or module under lib/, keep all of its unit tests in a single spec file under spec/ that mirrors the path and file name exactly: lib/cyclonedx/my_class.rb -> spec/cyclonedx/my_class_spec.rb.
  • Exception: Integration specs that intentionally span multiple classes. Place these under spec/integration/ (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.

Lint It

Run the linter.

bundle exec rake rubocop

Important: Do not add inline RuboCop disables

Try not to add # rubocop:disable ... / # rubocop:enable ... comments to code or specs (except when following the few existing rubocop:disable patterns for a rule already being disabled elsewhere in the code). Instead:

  • Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via .rubocop.yml).
    • bundle exec rubocop -a (preferred)
    • bundle exec rubocop --regenerate-todo (only when you cannot fix the violations immediately)

As a general rule, fix style issues rather than ignoring them. For example, our specs should follow RSpec conventions like using described_class for the class under test.

Sign off your commits

Please sign off your commits, to show that you agree to publish your changes under the current terms and licenses of the project , and to indicate agreement with Developer Certificate of Origin (DCO).

git commit --signed-off ...

Contributors

Your picture could be here!

Contributors

Made with contributors-img.

For Maintainers

To release a new version:

Automated process

Coming Soon!

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 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.
  12. 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
  13. Sanity check the SHA256, comparing with the output from the bin/gem_checksums command:
    • sha256sum pkg/<gem name>-<version>.gem