|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Any contribution is welcome. |
| 4 | +Please read the [CycloneDX contributing guidelines](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md) first. |
| 5 | + |
| 6 | +Pull-requests from forks are welcome. |
| 7 | +We love to see your purposed changes, but we also like to discuss things first. Please open a [ticket][📜src-gh] and explain your intended changes to the community. And don't forget to mention that discussion in your pull-request later. |
| 8 | +Find the needed basics here: |
| 9 | +* [how to fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) |
| 10 | +* [how create a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) |
| 11 | +* Remember to [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] if you make changes. |
| 12 | + |
| 13 | +## Setup |
| 14 | + |
| 15 | +This project uses ruby. Have a recent version installed and setup first. |
| 16 | + |
| 17 | +To install dev-dependencies and tools: |
| 18 | + |
| 19 | +```shell |
| 20 | +bin/setup |
| 21 | +``` |
| 22 | + |
| 23 | +## Environment Variables for Local Development |
| 24 | + |
| 25 | +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. |
| 26 | + |
| 27 | +General/runtime |
| 28 | +- 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) |
| 29 | +- ARUBA_NO_COVERAGE: Disable SimpleCov coverage in Aruba tests (default: false) |
| 30 | + |
| 31 | +Releasing and signing |
| 32 | +- SKIP_GEM_SIGNING: If set, skip gem signing during build/release |
| 33 | +- GEM_CERT_USER: Username for selecting your public cert in `certs/<USER>.pem` (defaults to $USER) |
| 34 | + |
| 35 | +For a quick starting point, this repository’s `.envrc` shows sane defaults, and `.env.local` can override them locally. |
| 36 | + |
| 37 | +## Testing |
| 38 | + |
| 39 | +To run all tests |
| 40 | + |
| 41 | +```console |
| 42 | +bundle exec rake test |
| 43 | +``` |
| 44 | + |
| 45 | +Or use the default task, which does the same |
| 46 | + |
| 47 | +```console |
| 48 | +bundle exec rake |
| 49 | +``` |
| 50 | + |
| 51 | +### Spec organization (required) |
| 52 | + |
| 53 | +- 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/undrive_google/release_cli.rb` -> `spec/undrive_google/release_cli_spec.rb`. |
| 54 | +- Never add a second spec file for the same class/module. Examples of disallowed names: `*_more_spec.rb`, `*_extra_spec.rb`, `*_status_spec.rb`, or any other suffix that still targets the same class. If you find yourself wanting a second file, merge those examples into the canonical spec file for that class/module. |
| 55 | +- 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. |
| 56 | +- Migration note: If a duplicate spec file exists, move all examples into the canonical file and delete the duplicate. Do not leave stubs or empty files behind. |
| 57 | + |
| 58 | +## Lint It |
| 59 | + |
| 60 | +Run the linter. |
| 61 | + |
| 62 | +```console |
| 63 | +bundle exec rake rubocop |
| 64 | +``` |
| 65 | + |
| 66 | +### Important: Do not add inline RuboCop disables |
| 67 | + |
| 68 | +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: |
| 69 | + |
| 70 | +- Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via `.rubocop.yml`). |
| 71 | + - `bundle exec rubocop -a` (preferred) |
| 72 | + - `bundle exec rubocop --regenerate-todo` (only when you cannot fix the violations immediately) |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +## Sign off your commits |
| 77 | + |
| 78 | +Please sign off your commits, to show that you agree to publish your changes under the current terms and licenses of the project |
| 79 | +, and to indicate agreement with [Developer Certificate of Origin (DCO)](https://developercertificate.org/). |
| 80 | + |
| 81 | +```shell |
| 82 | +git commit --signed-off ... |
| 83 | +``` |
| 84 | + |
| 85 | +## Contributors |
| 86 | + |
| 87 | +Your picture could be here! |
| 88 | + |
| 89 | +[![Contributors][🖐contributors-img]][🖐contributors] |
| 90 | + |
| 91 | +Made with [contributors-img][🖐contrib-rocks]. |
| 92 | + |
| 93 | +## For Maintainers |
| 94 | + |
| 95 | +### One-time, Per-maintainer, Setup |
| 96 | + |
| 97 | +**IMPORTANT**: To sign a build, |
| 98 | +a public key for signing gems will need to be picked up by the line in the |
| 99 | +`gemspec` defining the `spec.cert_chain` (check the relevant ENV variables there). |
| 100 | +All releases after v1.1.0 are signed releases. |
| 101 | +See: [RubyGems Security Guide][🔒️rubygems-security-guide] |
| 102 | + |
| 103 | +NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in the environment. Only do this for testing. |
| 104 | + |
| 105 | +### To release a new version: |
| 106 | + |
| 107 | +#### Automated process |
| 108 | + |
| 109 | +Coming Soon! |
| 110 | + |
| 111 | +#### Manual process |
| 112 | + |
| 113 | +1. Run `bin/setup && bin/rake` as a "test, coverage, & linting" sanity check |
| 114 | +2. Update the version number in `version.rb`, and ensure `CHANGELOG.md` reflects changes |
| 115 | +3. Run `bin/setup && bin/rake` again as a secondary check, and to update `Gemfile.lock` |
| 116 | +4. Run `git commit -am "🔖 Prepare release v<VERSION>"` to commit the changes |
| 117 | +5. Run `git push` to trigger the final CI pipeline before release, and merge PRs |
| 118 | + - NOTE: Remember to [check the build][🧪build]. |
| 119 | +6. Run `export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME` |
| 120 | +7. Run `git checkout $GIT_TRUNK_BRANCH_NAME` |
| 121 | +8. Run `git pull origin $GIT_TRUNK_BRANCH_NAME` to ensure latest trunk code |
| 122 | +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 |
| 123 | + - If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default. |
| 124 | + - Run `export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH` |
| 125 | + - If the echo above has no output, then it didn't work. |
| 126 | + - Note: `zsh/datetime` module is needed, if running `zsh`. |
| 127 | + - In older versions of `bash` you can use `date +%s` instead, i.e. `export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH` |
| 128 | +10. Run `bundle exec rake build` |
| 129 | +11. Run `bundle exec rake release` which will create a git tag for the version, |
| 130 | + push git commits and tags, and push the `.gem` file to the gem host configured in the gemspec. |
| 131 | +12. Run `bin/gem_checksums` (more context [1][🔒️rubygems-checksums-pr], [2][🔒️rubygems-guides-pr]) |
| 132 | + to create SHA-256 and SHA-512 checksums. This functionality is provided by the `stone_checksums` |
| 133 | + [gem][💎stone_checksums]. |
| 134 | + - The script automatically commits but does not push the checksums |
| 135 | +13. Sanity check the SHA256, comparing with the output from the `bin/gem_checksums` command: |
| 136 | + - `sha256sum pkg/<gem name>-<version>.gem` |
| 137 | + |
| 138 | +[📜src-gh]: https://github.com/CycloneDX/cyclonedx-ruby-gem |
| 139 | +[🧪build]: https://github.com/CycloneDX/cyclonedx-ruby-gem/actions |
| 140 | +[🤝conduct]: https://gitlab.com/CycloneDX/cyclonedx-ruby-gem/-/blob/main/CODE_OF_CONDUCT.md |
| 141 | +[🖐contrib-rocks]: https://contrib.rocks |
| 142 | +[🖐contributors]: https://github.com/CycloneDX/cyclonedx-ruby-gem/graphs/contributors |
| 143 | +[🖐contributors-img]: https://contrib.rocks/image?repo=CycloneDX/cyclonedx-ruby-gem |
| 144 | +[💎gem-coop]: https://gem.coop |
| 145 | +[🔒️rubygems-security-guide]: https://guides.rubygems.org/security/#building-gems |
| 146 | +[🔒️rubygems-checksums-pr]: https://github.com/rubygems/rubygems/pull/6022 |
| 147 | +[🔒️rubygems-guides-pr]: https://github.com/rubygems/guides/pull/325 |
| 148 | +[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums |
| 149 | +[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/ |
| 150 | +[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat |
| 151 | +[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139 |
| 152 | +[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html |
| 153 | +[🏃♂️runner-tool-cache]: https://github.com/ruby/ruby-builder/releases/tag/toolcache |
0 commit comments