2018-09-16 04:36:22 +00:00
|
|
|
# Maintaining Shoulda Matchers
|
|
|
|
|
|
|
|
As maintainers of the gem, this is our guide. Most of the steps and guidelines
|
|
|
|
in the [Contributing](CONTRIBUTING.md) document apply here, including how to set
|
|
|
|
up your environment, write code to fit the code style, run tests, craft commits
|
|
|
|
and manage branches. Beyond this, this document provides some details that would
|
|
|
|
be too low-level for contributors.
|
|
|
|
|
|
|
|
## Communication
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
We have several ways that we can communicate with each other:
|
2018-09-16 04:36:22 +00:00
|
|
|
|
|
|
|
* In planning major releases, it can be helpful to create a **new issue**
|
|
|
|
outlining the changes as well as steps needed to launch the release. This
|
|
|
|
serves both as an announcement to the community as well as an area to keep a
|
|
|
|
checklist.
|
|
|
|
* To track progress for the next release, **GitHub milestones** are useful.
|
|
|
|
* To track progress on the movement of issues, [**labels**](#addendum-labels)
|
|
|
|
are useful.
|
|
|
|
* To communicate small-scale changes, **pull requests** are effective, as
|
|
|
|
mentioned above.
|
|
|
|
* To communicate large-scale changes or explain topics, **email** is best.
|
|
|
|
|
|
|
|
## Managing the community
|
|
|
|
|
|
|
|
As anyone who has played a sim game before, it's important to make your patrons
|
|
|
|
happy. We do this by:
|
|
|
|
|
|
|
|
* Answering questions from members of the community
|
|
|
|
* Closing stale issues and feature requests
|
|
|
|
* Keeping the community informed by ensuring that the changelog is up to date
|
|
|
|
* Ensuring that the inline documentation, as well as the docsite, is kept up to
|
|
|
|
date
|
|
|
|
|
|
|
|
## Workflow
|
|
|
|
|
|
|
|
We generally follow [GitHub Flow]. The `master` branch is the main line, and all
|
|
|
|
branches are cut from and get merged back into this branch. Generally, the
|
|
|
|
workflow is as follows:
|
|
|
|
|
|
|
|
[GitHub Flow]: https://help.github.com/articles/github-flow/
|
|
|
|
|
|
|
|
* Cut a feature or bugfix branch from this branch.
|
|
|
|
* Upon completing a branch, create a PR and ask another maintainer to approve
|
|
|
|
it.
|
|
|
|
* Try to keep the commit history as clean as possible. Before merging, squash
|
|
|
|
"WIP" or related commits together and rebase as needed.
|
|
|
|
* Once your PR is approved and you've cleaned up your branch, you're free to
|
|
|
|
merge it in.
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
Besides the matchers, there are files in `lib` which you may need to reference
|
|
|
|
or update:
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
* `lib/shoulda/matchers/doublespeak*` — a small handrolled mocking library
|
2018-09-16 04:36:22 +00:00
|
|
|
which is used by the `permit` matcher
|
2019-02-16 18:23:07 +00:00
|
|
|
* `lib/shoulda/matchers/util*` — extra methods which are used in various places
|
2018-09-16 04:36:22 +00:00
|
|
|
to detect library versions, wrap/indent text, and more
|
|
|
|
|
2019-02-16 18:23:48 +00:00
|
|
|
## Running tests
|
|
|
|
|
|
|
|
The CONTRIBUTING guide shows how to use Appraisal to run tests. This works well
|
|
|
|
if you are hopping in, making a few changes, and hopping right out, but if you
|
|
|
|
plan on working on a feature or bug, there is often a faster alternative, at
|
|
|
|
least for unit tests: [Zeus]. Zeus works by preloading the Rails environment so
|
|
|
|
that running unit tests are a lot faster. We also have it set up to
|
|
|
|
automatically select the latest Appraisal so you don't have to provide that.
|
|
|
|
|
|
|
|
You'll want to start by running `zeus start` in one shell. Then in another
|
|
|
|
shell, instead of using `bundle exec rspec` to run tests, you'll use `bundle
|
|
|
|
exec zeus rspec`. So for instance, you might say:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec zeus rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb
|
|
|
|
```
|
|
|
|
|
|
|
|
This is long to say, but it helps if you add an alias to your shell:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
alias zr="bundle exec zeus rspec"
|
|
|
|
```
|
|
|
|
|
|
|
|
[Zeus]: https://github.com/burke/zeus
|
|
|
|
|
2018-09-16 04:36:22 +00:00
|
|
|
## Updating the changelog
|
|
|
|
|
|
|
|
After every user-facing change makes it into master, we make a note of it in the
|
|
|
|
changelog, which for historical reasons is kept in `NEWS.md`. The changelog is
|
|
|
|
sorted in reverse order by release version, with the topmost version as the next
|
|
|
|
release (tagged as "(Unreleased)").
|
|
|
|
|
|
|
|
Within each version, there are five available categories you can divide changes
|
|
|
|
into. They are all optional but they should appear in this order:
|
|
|
|
|
|
|
|
1. Backward-compatible changes
|
|
|
|
1. Deprecations
|
|
|
|
1. Bug fixes
|
|
|
|
1. Features
|
|
|
|
1. Improvements
|
|
|
|
|
|
|
|
Within each category section, the changes relevant to that category are listed
|
|
|
|
in chronological order.
|
|
|
|
|
|
|
|
For each change, provide a human-readable description of the change as well as a
|
|
|
|
linked reference to the PR where that change emerged (or the commit ID if no
|
|
|
|
such PR is available). This helps users cross-reference changes if they need to.
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
|
|
### Generating documentation
|
|
|
|
|
|
|
|
As mentioned in the Contributing document, we use YARD for documentation. YARD
|
|
|
|
is configured via `.yardopts` to process the Ruby files in `lib/` as well as
|
|
|
|
`NEWS.md` and the Markdown files in `docs/` and write the documentation in HTML
|
|
|
|
form to `doc`. This command will do exactly that:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec yard doc
|
|
|
|
```
|
|
|
|
|
|
|
|
However, if you're actively updating the documentation, it's more helpful to
|
|
|
|
launch a process that will watch the aforementioned source files for changes and
|
|
|
|
generate the HTML for you automatically:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec rake docs:autogenerate
|
|
|
|
```
|
|
|
|
|
|
|
|
Whichever approach you take, you can view the generated docs locally by running:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
open doc/index.html
|
|
|
|
```
|
|
|
|
|
|
|
|
### About the docsite
|
|
|
|
|
|
|
|
The docfiles that YARD generates are published to the docsite, which is located
|
|
|
|
at:
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
<https://matchers.shoulda.io>
|
|
|
|
|
|
|
|
The docsite is hosted on GitHub Pages*. As such, the `gh-pages` branch hosts its
|
|
|
|
code. Usually you don't need to update this branch directly unless you want to
|
|
|
|
make changes to the homepage itself. As for the *documentation*, it is hosted
|
|
|
|
one level deeper:
|
2018-09-16 04:36:22 +00:00
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
<https://matchers.shoulda.io/docs>
|
2018-09-16 04:36:22 +00:00
|
|
|
|
2019-02-16 18:23:48 +00:00
|
|
|
The URL above actually links to a HTML page which merely serves to automatically
|
|
|
|
redirect the visitor to the docs for the latest published version of the gem.
|
|
|
|
This version is hardcoded in the HTML page, but is also updated automatically by
|
|
|
|
the `docs:publish` and `docs:publish_latest` tasks.
|
2018-09-16 04:36:22 +00:00
|
|
|
|
|
|
|
*\* thoughtbot owns <https://shoulda.io>, and
|
|
|
|
they've got `matchers.shoulda.io` set up on the DNS level as an alias for
|
|
|
|
`thoughtbot.github.io/shoulda-matchers`.*
|
|
|
|
|
|
|
|
## Versioning
|
|
|
|
|
|
|
|
### Naming a new version
|
|
|
|
|
|
|
|
As designated in the README, we follow [SemVer 2.0][semver]. This offers a
|
|
|
|
meaningful baseline for deciding how to name versions. Generally speaking:
|
|
|
|
|
|
|
|
[semver]: https://semver.org/spec/v2.0.0.html
|
|
|
|
|
|
|
|
* We bump the "major" part of the version if we're introducing
|
|
|
|
backward-incompatible changes (e.g. changing the API or core behavior,
|
|
|
|
removing parts of the API, or dropping support for a version of Ruby).
|
|
|
|
* We bump the "minor" part if we're adding a new feature (e.g. adding a new
|
|
|
|
matcher or adding a new qualifier to a matcher).
|
|
|
|
* We bump the "patch" part if we're merely including bugfixes.
|
|
|
|
|
|
|
|
In addition to major, minor, and patch levels, you can also append a
|
|
|
|
suffix to the version for pre-release versions. We usually use this to issue
|
|
|
|
release candidates prior to an actual release. A version number in this case
|
|
|
|
might look like `4.0.0.rc1`.
|
|
|
|
|
|
|
|
### Releasing a new version
|
|
|
|
|
|
|
|
Releasing a new version is very simple:
|
|
|
|
|
|
|
|
1. First, you'll want to be given ownership permissions for the Ruby gem itself.
|
|
|
|
If you want to give someone else these rights, you can use:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
gem owner shoulda-matchers -a <email address>
|
|
|
|
```
|
|
|
|
1. Next, you'll want to update the `VERSION` constant in
|
|
|
|
`lib/shoulda/matchers/version.rb`. This constant is referenced in the gemspec
|
|
|
|
and is used in the Rake tasks to publish the gem on RubyGems as well as
|
|
|
|
generate documentation.
|
|
|
|
1. Finally, you'll want to run:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
rake release
|
|
|
|
```
|
|
|
|
|
|
|
|
This will not only push the gem to RubyGems, but also update the docsite.
|
|
|
|
|
|
|
|
### Re-publishing docs
|
|
|
|
|
|
|
|
In general you'll use the `release` task to update the docsite, but there may be
|
2019-02-16 18:23:07 +00:00
|
|
|
situations where you'll need to do it manually.
|
2018-09-16 04:36:22 +00:00
|
|
|
|
|
|
|
You can re-publish the docs for the latest version (as governed by
|
|
|
|
`lib/shoulda/matchers/version.rb`) by running:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec rake docs:publish_latest
|
|
|
|
```
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
This will update the auto-redirect on the index page to the latest version. For
|
|
|
|
instance, if the latest version were 4.0.0, this command would publish the docs
|
|
|
|
at <https://matchers.shoulda.io/docs/v4.0.0> and simultaneously redirect
|
2018-09-16 04:36:22 +00:00
|
|
|
<https://matchers.shoulda.io/docs> to this location.
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
However, if you want to publish the docs for a version but manually set the
|
|
|
|
auto-redirected version, you can run this instead:
|
2018-09-16 04:36:22 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec rake docs:publish[version, latest_version]
|
|
|
|
```
|
|
|
|
|
|
|
|
Here, `version` and `latest_version` are both version strings. For instance, you
|
|
|
|
might say:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
bundle exec rake docs:publish[4.0.0, 3.7.2]
|
|
|
|
```
|
|
|
|
|
|
|
|
This would publish the docs for 4.0.0 at
|
|
|
|
<https://matchers.shoulda.io/docs/v4.0.0>, but redirect
|
|
|
|
<https://matchers.shoulda.io/docs> to <https://matchers.shoulda.io/docs/v3.7.2>.
|
|
|
|
|
|
|
|
## Addendum: Labels
|
|
|
|
|
2019-02-16 18:23:07 +00:00
|
|
|
Considering that we work on the gem in our spare time, we've found [labels] to
|
|
|
|
be useful for cataloguing and marking progress. Over time we've added quite a
|
|
|
|
collection of labels. Here's a quick list:
|
2018-09-16 04:36:22 +00:00
|
|
|
|
|
|
|
[labels]: https://github.com/thoughtbot/shoulda-matchers/labels
|
|
|
|
|
|
|
|
### Labels for issues
|
|
|
|
|
|
|
|
* **Issue: Bug**
|
|
|
|
* **Issue: Feature Request**
|
2019-02-16 18:23:07 +00:00
|
|
|
* **Issue: Need to Investigate** — if we don't know whether a bug is legitimate
|
2018-09-16 04:36:22 +00:00
|
|
|
or not
|
2019-02-16 18:23:07 +00:00
|
|
|
* **Issue: PR Needed** — perhaps unnecessary, but it does signal to the
|
2018-09-16 04:36:22 +00:00
|
|
|
community that we'd love a PR
|
|
|
|
|
|
|
|
### Labels for PRs
|
|
|
|
|
|
|
|
* **PR: Bugfix**
|
|
|
|
* **PR: Feature**
|
2019-02-16 18:23:07 +00:00
|
|
|
* **PR: Good to Merge** — most of the time not necessary, but can be helpful in
|
2018-09-16 04:36:22 +00:00
|
|
|
a code freeze before a release to mark PRs that we will include in the next
|
|
|
|
release
|
2019-02-16 18:23:07 +00:00
|
|
|
* **PR: In Progress** — used to mark PRs that are still being worked on by the
|
2018-09-16 04:36:22 +00:00
|
|
|
PR author
|
|
|
|
* **PR: Needs Documentation**
|
|
|
|
* **PR: Needs Review**
|
|
|
|
* **PR: Needs Tests**
|
2019-02-16 18:23:07 +00:00
|
|
|
* **PR: Needs Updates Before Merge** — along the same lines as the other
|
2018-09-16 04:36:22 +00:00
|
|
|
"Needs" tags, but more generic
|
|
|
|
|
|
|
|
### Generic labels
|
|
|
|
|
|
|
|
* **Blocked**
|
|
|
|
* **Documentation**
|
|
|
|
* **Needs Decision**
|
|
|
|
* **Needs Revisiting**
|
|
|
|
* **Question**
|
|
|
|
* **Rails X**
|
|
|
|
* **Ruby X.Y**
|
|
|
|
* **UX**
|