https://github.com/stitchfix/merch_calendar
Calculations around the National Retail Federation's 4-5-4 calendar
https://github.com/stitchfix/merch_calendar
Last synced: about 1 year ago
JSON representation
Calculations around the National Retail Federation's 4-5-4 calendar
- Host: GitHub
- URL: https://github.com/stitchfix/merch_calendar
- Owner: stitchfix
- License: mit
- Created: 2015-05-06T20:39:04.000Z (about 11 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T14:26:59.000Z (over 1 year ago)
- Last Synced: 2025-04-01T15:39:06.893Z (over 1 year ago)
- Language: Ruby
- Homepage:
- Size: 168 KB
- Stars: 14
- Watchers: 117
- Forks: 5
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Merch Calendar
[](http://badge.fury.io/rb/merch_calendar)
[](https://travis-ci.org/stitchfix/merch_calendar)
[](https://codeclimate.com/github/stitchfix/merch_calendar)
[](https://coveralls.io/r/stitchfix/merch_calendar)
This gem allows for finding retail/merchandising weeks for a given date, along with manipulating the retail calendar.
This gem is used at [Stitch Fix](http://www.stitchfix.com/).
## Installation
```bash
$ gem install merch_calendar
```
Add the following line to your `Gemfile`:
```ruby
gem "merch_calendar"
```
## Ruby Version Compatibility
This gem has been tested against Ruby 2.0 - 2.4.
Support for Ruby 1.9.3 was discontinued as of version 0.3.0 of this gem. If you're on Ruby 1.9.3, you'll want to
install the gem like so:
```ruby
gem "merch_calendar", "0.3.0"
```
## Usage
For converting a date into a `MerchWeek` object.
```ruby
merch_week = MerchCalendar::MerchWeek.from_date("2014-01-01", calendar: MerchCalendar::RetailCalendar.new)
merch_week.year # 2013 (the merch year associated with this date)
merch_week.month # 12 (the julian month that the date falls in)
merch_week.week # 5 (the week number within the month)
merch_week.year_week # 48 (the week number within the retail calendar year)
merch_week.quarter # 4
merch_week.start_of_week #
merch_week.end_of_week #
merch_week.start_of_month #
merch_week.end_of_month #
merch_week.start_of_year #
merch_week.end_of_year #
merch_week.calendar # (the calendar we're using)
# if you don't initialize a calendar, it defaults to RetailCalendar
# Formatting
merch_week.to_s # "Dec W5"
merch_week.to_s(:short) # "Dec W5"
merch_week.to_s(:long) # "2013:48 Dec W5"
merch_week.to_s(:elasticsearch) # "2013-12w05"
```
### Merch retail calendar
Retail calendars have their first month in February, and the last (12th) month is in January of the
following year.
```ruby
# This is asking "In the Merch year of 2014, what is the Gregorian calendar date of
# the start of the first month?"
retail_calendar = MerchCalendar::RetailCalendar.new
retail_calendar.start_of_month(2014, 1)
# => 2014-02-02
retail_calendar.start_of_month(2014, 12)
# => 2015-01-04
```
This table should describe the progression of dates:
| N | `start_of_month(2014, N)` |
| ------------- | ------------- |
| 1 | 2014-02-02 |
| 2 | 2014-03-02 |
| 3 | 2014-04-06 |
| 4 | 2014-05-04 |
| 5 | 2014-06-01 |
| 6 | 2014-07-06 |
| 7 | 2014-08-03 |
| 8 | 2014-08-31 |
| 9 | 2014-10-05 |
| 10 | 2014-11-02 |
| 11 | 2014-11-30 |
| 12 | 2015-01-04 |
Other useful methods:
```ruby
# 52 or 53 (depending on leap year)
retail_calendar.weeks_in_year(2016)
# => 52
retail_calendar.weeks_in_year(2017)
# => 53
# get the start date of a given merch week
retail_calendar.start_of_week(2017, 4, 1)
# => #
# get the end date of a given merch week
retail_calendar.end_of_week(2017, 4, 1)
#=> #
```
### Stitch Fix Fiscal Year Calendars
Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that instead starts in August
rather than in February in a the traditional retail calendar. The `MerchCalendar::StitchFixFiscalYearCalendar` class
allows you to easily translate Gregorian dates to a Stitch Fix Fiscal Year date.
```ruby
fiscal_calendar = MerchCalendar::StitchFixFiscalYearCalendar.new
fiscal_calendar.weeks_in_year(2018)
# => 52
fiscal_calendar.weeks_in_year(2019)
# => 53
# get the start date of a given merch week
fiscal_calendar.start_of_week(2017, 1, 1)
# => #
# get the end date of a given merch week
fiscal_calendar.end_of_week(2017, 4, 1)
#=> #
```
#### Stitch Fix Fiscal Year Calendar in Relation to MerchWeek object
You can set MerchWeek object respond to the Stitch Fix Fiscal Calendar, by passing in `StitchFixFiscalYearCalendar.new` in the calendar parameter:
```ruby
merch_week = MerchCalendar::MerchWeek.from_date("2018-07-02", calendar: MerchCalendar::StitchFixFiscalYearCalendar.new)
merch_week.year # 2018 (the merch year associated with this date)
merch_week.month # 7 (the julian month that the date falls in)
merch_week.merch_month # 12 (this fiscal month the date falls in)
merch_week.week # 1 (the week number within the month)
merch_week.year_week # 49 (the week number within the retail calendar year)
merch_week.quarter # 4
merch_week.start_of_week #
merch_week.end_of_week #
merch_week.start_of_month #
merch_week.end_of_month #
merch_week.start_of_year #
merch_week.end_of_year #
merch_week.calendar # (the calendar
# we're using)
# if you don't initialize a calendar, it defaults to RetailCalendar
# Formatting
merch_week.to_s # "Jul W1"
merch_week.to_s(:short) # "Jul W1"
merch_week.to_s(:long) # "2018:49 Jul W1"
merch_week.to_s(:elasticsearch) # "2018-07w01"
```
## Documentation
You can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).
## License
MerchCalendar is released under the [MIT License](http://www.opensource.org/licenses/MIT).