|
| 1 | +# Maintaining Shoulda Context |
| 2 | + |
| 3 | +Although Shoulda Context doesn't receive feature updates these days, you may |
| 4 | +need to update the gem for new versions of Ruby or Rails. Here's what you need |
| 5 | +to know in order to do that. |
| 6 | + |
| 7 | +## Getting started |
| 8 | + |
| 9 | +First, run the setup script: |
| 10 | + |
| 11 | + bin/setup |
| 12 | + |
| 13 | +Then run all the tests to make sure everything is green: |
| 14 | + |
| 15 | + bundle exec rake |
| 16 | + |
| 17 | +## Running tests |
| 18 | + |
| 19 | +This project uses Minitest for tests and Appraisal to create environments |
| 20 | +attuned for different versions of Rails. To run a single test in a single test |
| 21 | +file, you will need to use a combination of Appraisal and the [`m`][m] gem. For |
| 22 | +instance: |
| 23 | + |
| 24 | +[m]: https://github.com/qrush/m |
| 25 | + |
| 26 | + bundle exec appraisal rails_6_0 m test/shoulda/context_test.rb:39 |
| 27 | + |
| 28 | +## Updating the changelog |
| 29 | + |
| 30 | +After every user-facing change makes it into master, we make a note of it in the |
| 31 | +changelog, kept in `CHANGELOG.md`. The changelog is sorted in reverse order by |
| 32 | +release version, with the topmost version as the next release (tagged as |
| 33 | +"(Unreleased)"). |
| 34 | + |
| 35 | +Within each version, there are five available categories you can divide changes |
| 36 | +into. They are all optional but they should appear in this order: |
| 37 | + |
| 38 | +1. Backward-compatible changes |
| 39 | +1. Deprecations |
| 40 | +1. Bug fixes |
| 41 | +1. Features |
| 42 | +1. Improvements |
| 43 | + |
| 44 | +Within each category section, the changes relevant to that category are listed |
| 45 | +in chronological order. |
| 46 | + |
| 47 | +For each change, provide a human-readable description of the change as well as a |
| 48 | +linked reference to the PR where that change emerged (or the commit ID if no |
| 49 | +such PR is available). This helps users cross-reference changes if they need to. |
| 50 | + |
| 51 | +## Versioning |
| 52 | + |
| 53 | +### Naming a new version |
| 54 | + |
| 55 | +As designated in the README, we follow [SemVer 2.0][semver]. This offers a |
| 56 | +meaningful baseline for deciding how to name versions. Generally speaking: |
| 57 | + |
| 58 | +[semver]: https://semver.org/spec/v2.0.0.html |
| 59 | + |
| 60 | +* We bump the "major" part of the version if we're introducing |
| 61 | + backward-incompatible changes (e.g. changing the API or core behavior, |
| 62 | + removing parts of the API, or dropping support for a version of Ruby). |
| 63 | +* We bump the "minor" part if we're adding a new feature (e.g. adding a new |
| 64 | + matcher or adding a new qualifier to a matcher). |
| 65 | +* We bump the "patch" part if we're merely including bugfixes. |
| 66 | + |
| 67 | +In addition to major, minor, and patch levels, you can also append a |
| 68 | +suffix to the version for pre-release versions. We usually use this to issue |
| 69 | +release candidates prior to an actual release. A version number in this case |
| 70 | +might look like `4.0.0.rc1`. |
| 71 | + |
| 72 | +### Preparing and releasing a new version |
| 73 | + |
| 74 | +In order to release any versions at all, you will need to have been added as |
| 75 | +an owner of the Ruby gem. If you want to give someone else these permissions, |
| 76 | +then run: |
| 77 | + |
| 78 | +```bash |
| 79 | +gem owner shoulda-context -a <email address> |
| 80 | +``` |
| 81 | + |
| 82 | +Assuming you have permission to publish a new version to RubyGems, then this is |
| 83 | +how you release a version: |
| 84 | + |
| 85 | +1. First, you'll want to [make sure that the changelog is up to |
| 86 | + date](#updating-the-changelog). |
| 87 | + |
| 88 | +2. Next, you'll want to update the `VERSION` constant in |
| 89 | + `lib/shoulda/context/version.rb`. This constant is referenced in the |
| 90 | + gemspec and is used in the Rake tasks to publish the gem on RubyGems. |
| 91 | + |
| 92 | +3. Assuming that everything looks good, place your changes to the changelog, |
| 93 | + `version.rb`, and README in their own commit titled "Bump version to |
| 94 | + *X.Y.Z*". Push this to GitHub (you can use `[ci skip]`) in the body of the |
| 95 | + commit message to skip CI for this commit if you so choose). **There is no |
| 96 | + going back after this point!** |
| 97 | + |
| 98 | +6. Once GitHub has the version-change commit, you will run: |
| 99 | + |
| 100 | + ```bash |
| 101 | + rake release |
| 102 | + ``` |
| 103 | + |
| 104 | + This will push the gem to RubyGems and make it available for download. |
0 commit comments