Skip to content

Commit

Permalink
📚 Add compatibility policy to README.md
Browse files Browse the repository at this point in the history
I saw a chart similar to this in ruby/openssl's README, and it seems
like this is a relatively simple way to communicate our versioning.

I'll propose documentation for a slightly more detailed policy in a
future PR.
  • Loading branch information
nevans committed May 3, 2024
1 parent 119f43a commit e09388e
Showing 1 changed file with 39 additions and 0 deletions.
39 changes: 39 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,45 @@ end
imap.expunge
```

## Compatibility and Maintenance Policy

`net-imap` is bundled with Ruby releases. As a [bundled gem], it can be
uninstalled from a Ruby installation and must be declared in `Gemfile` when used
with `bundler`. Each Ruby `major.minor` release series will be pinned to a
specific `net-imap` `major.minor` release series, and will only bundle releases
from that series. Each `net-imap` release series will receive security updates
as long as they are bundled with [supported Ruby branches]. The latest stable
Ruby release series may also receive backported bugfixes and features, at the
maintainers' discretion.

|net-imap |ruby |maintenance level |
|---------|---------------|--------------------------------------|
|current |main (dev) |new features (and deprecations) |
|current-1|current stable |discretionary backported bugfixes, etc|
|current-2|previous stable|security maintenance |
|current-3|oldest stable |security maintenance |
|_older_ |_older_ |end of life |

### Release series

| |Bundled with|Compatible with|First bundled release |Supported? |
|-----|------------|---------------|-----------------------------|--------------|
|0.5.x| _not yet_ | Ruby 3.1+ |_future Ruby 3.4 release_ |new features |
|0.4.x| Ruby 3.3 | Ruby 2.7.3+ |0.4.9, Ruby 3.3.0, 2023-12-25|some backports|
|0.3.x| Ruby 3.2 | Ruby 2.6+ |0.3.4, Ruby 3.2.0, 2022-12-25|security only |
|0.2.x| Ruby 3.1 | Ruby 2.5+/2.6+|0.2.2, Ruby 3.1.0, 2021-12-25|security only |
|0.1.x| Ruby 3.0* | Ruby 2.5+ |0.1.1, Ruby 3.0.0, 2020-12-25|end of life |
|_pre_| in stdlib | | Ruby 1.6.2, 2000-12-25|end of life |

Version 0.1.x was packaged as a [default gem] for Ruby 3.0, and can not be
uninstalled from a Ruby 3.0 installation. Before being extracted into a gem,
`net/imap` was only packaged as a part of Ruby's releases. The first stable
release to include `net/imap` was ruby 1.6.2, on 2000-12-25.

[bundled gem]: https://docs.ruby-lang.org/en/master/standard_library_rdoc.html#label-Bundled+gems
[default gem]: https://docs.ruby-lang.org/en/master/standard_library_rdoc.html
[supported Ruby branches]: https://www.ruby-lang.org/en/downloads/branches/

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
Expand Down

0 comments on commit e09388e

Please sign in to comment.