README.md in boolean_timestamp-0.2.1 vs README.md in boolean_timestamp-1.0.0
- old
+ new
@@ -1,8 +1,8 @@
# BooleanTimestamp
-[](https://travis-ci.org/molawson/boolean_timestamp)
+[](https://travis-ci.org/molawson/boolean_timestamp)
[](https://codeclimate.com/github/molawson/boolean_timestamp/maintainability)
[](https://codeclimate.com/github/molawson/boolean_timestamp/test_coverage)
True/False fields have a great simplicity about them, and many times they're perfect for the job!
But, it's not uncommon end up in a place where you'd really love to keep some degree of simplicity with a little more detail about when the value was changed.
@@ -19,39 +19,98 @@
And then execute:
$ bundle
-Or install it yourself as:
+Or install it yourself with:
$ gem install boolean_timestamp
## Usage
+### Model Setup
In any `ActiveRecord` model, you can define a boolean field based on a timestamp column by including the `BooleanTimestmap` module and calling a single method.
```ruby
class Article < ActiveRecord::Base
include BooleanTimestamp
- boolean_timestamp :published # works with an existing column named `published_at`
+ boolean_timestamp :published
end
```
-The gem doesn't provide any code for setting up the database column. You'll need to use Rails migrations (or any other means you choose) to create the tables and columns you need.
+### Database Requirements
+The only requirement is that you have a time-based column with a matching name, including the standard `_at` suffix. In the example above, you'd need an `articles.published_at` column.
+The gem does not provide any code for setting up the database column. You'll need to use Rails migrations (or any other means you choose) to create the tables and columns you need.
+
+### Convenience Methods
+With this model setup, you get a number of methods for reading, writing, and querying a timestamp column as if it were a boolean, without restricting or altering any of the attributes that Rails adds for accessing the column directly.
+
+```ruby
+article = Article.new
+article.published? # => false
+
+article.published = true
+article.published? # => true
+article.published_at # => 2021-03-25 10:00:00 -0500
+
+Article.new(published_at: Time.now).published? # => true
+
+published = Article.create(title: "Published", published: true)
+draft = Article.create(title: "Draft")
+future = Article.create(title: "Future", published_at: Time.now + 86400)
+Article.published # => [published]
+Article.not_published # => [draft, future]
+```
+
+### (Not-so-)Strict Mode
+
+By default, `boolean_timestamp` is strict about which `Time` values are considered `true` or `false`. A value in the future is considered false because if an article has a `published_at` value of "tomorrow at noon", then strictly speaking it hasn't been published yet.
+
+This is most useful in circumstances where you really care about that time value. For example, being strict about this lets you add features like auto-publishing articles at a future date. A user can finish writing the article and set a future `published_at` value when they want the article to be "released", and any query that fetches published articles will automatically start including it after we reach the `published_at` time.
+
+In other cases, it's useful to have the timestamp value for debugging and reporting, but for all other intents and purposes, your code treats this data as boolean column. For example, you could have a `payments.failed_at` column. The timestamp is there mostly for historical reasons, the primary functio of that column is about separating the failed payments from those that didn't fail. You're not using this "a future value is falsey" feature of the library, but every time you lookup failed payments with `Payment.failed`, the query is going to use the current time, which can be needlessly slow (for this use-case) and is more difficult to cache (either explicitly in application code or by the database engine itself).
+
+You can disable the current time checks for both querying and reading values on a per-attribute basis by passing the `strict: false` option. This will only treat `nil` values as `false`. Everything else is `true`. This does not change how values are written to the database.
+
+```ruby
+class Article < ActiveRecord::Base
+ include BooleanTimestamp
+ boolean_timestamp :published, strict: false
+end
+
+published = Article.create(title: "Published", published: true)
+draft = Article.create(title: "Draft")
+future = Article.create(title: "Future", published: Time.now + 86400)
+
+# Where things start to behave differently
+
+future.published? # => true
+Article.published # => [published, future]
+Article.not_published # => [draft]
+```
+
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then 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 [rubygems.org](https://rubygems.org).
+You can run the tests with `bundle exec rake`. That will run the tests against the latest version of Rails (from Gemfile.lock) and the SQLite database, so you'll need to have SQLite setup locally. You can also run the tests selectively against another database with `bundle exec rake spec:mysql` or `bundle exec rake spec:postgres`. Or run all three database engine tests with `bundle exec rake spec:all`.
+If you're feeling even more ambitious, this project uses [appraisal](https://github.com/thoughtbot/appraisal) to test against multiple versions of `ActiveRecord`. You can get all of those tests setup with `bundle exec appraisal install` and run them all with `bundle exec appraisal rake spec:all` (see the appraisal docs for more usage info, including running a single appraisal).
+
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/molawson/boolean_timestamp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+1. Fork it ( https://github.com/molawson/repeatable/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
-Everyone interacting in the BooleanTimestamp project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/molawson/boolean_timestamp/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the BooleanTimestamp project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/molawson/boolean_timestamp/blob/main/CODE_OF_CONDUCT.md).