README.md in merch_calendar-0.1.0.rc2 vs README.md in merch_calendar-0.1.0.rc3
- old
+ new
@@ -47,84 +47,87 @@
puts merch_week.to_s(:short) # "Dec W5"
puts merch_week.to_s(:long) # "2013:48 Dec W5"
puts merch_week.to_s(:elasticsearch) # "2013-12w05"
```
-This can also be used on the `MerchCalendar` module. All `start_` and `end_` methods can be called, along with a few additional ones.
-```ruby
-# All examples below return a Date object for the start of May within the 2014 merch year
-MerchCalendar.start_of_month(2014, 5)
-MerchCalendar.start_of_month(2014, month: 5)
-MerchCalendar.start_of_month(2014, julian_month: 5)
+### Merch retail calendar
-# This is the same as May, because "Merch" months are shifted by 1.
-# i.e. month 1 is actually February
-# You probably will never use this, but it is available.
-MerchCalendar.start_of_month(2014, merch_month: 4)
-```
+Merch calendars have their first month in February, and the last (12th) month is in January of the
+following year.
-#### Confusing things to look out for:
-
-Merch calendars have the first month in February, and the last (12th) month is in January of the following year. In the code block above, each method is *asking* a very different question. This will definitely cause confusion, so here are some explanations.
-
```ruby
-# This is asking "In the Merch year of 2014, where is the month of January?"
-# January is the last (12th) month of a merch year, so this date will be in the NEXT
-# julian calendar year
-MerchCalendar.start_of_month(2014, 1)
-MerchCalendar.start_of_month(2014, month: 1)
-MerchCalendar.start_of_month(2014, julian_month: 1)
-# => 2015-01-04
-# ^^^^ - NEXT year
+# 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
-# This is asking "When is the start of the FIRST month of the merch year 2014"
-MerchCalendar.start_of_month(2014, merch_month: 1)
+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)` | `start_of_month(2014, merch_month: N)` |
-| ------------- | ------------- | ------------- |
-| 1 | **2015-01-04** | 2014-02-02 |
-| 2 | 2014-02-02 | 2014-03-02 |
-| 3 | 2014-03-02 | 2014-04-06 |
-| 4 | 2014-04-06 | 2014-05-04 |
-| 5 | 2014-05-04 | 2014-06-01 |
-| 6 | 2014-06-01 | 2014-07-06 |
-| 7 | 2014-07-06 | 2014-08-03 |
-| 8 | 2014-08-03 | 2014-08-31 |
-| 9 | 2014-08-31 | 2014-10-05 |
-| 10 | 2014-10-05 | 2014-11-02 |
-| 11 | 2014-11-02 | 2014-11-30 |
-| 12 | 2014-11-30 | **2015-01-04** |
+| 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)
-MerchCalendar.weeks_in_year(2015)
+retail_calendar.weeks_in_year(2016)
+# => 52
+retail_calendar.weeks_in_year(2017)
+# => 53
-# returns an array of MerchWeek objects for each week within the provided month
-MerchCalendar.weeks_for_month(2014, 1)
+# get the start date of a given merch week
+retail_calendar.start_of_week(2017, 4, 1)
+# => #<Date: 2017-04-30 ((2457874j,0s,0n),+0s,2299161j)>
+# get the end date of a given merch week
+retail_calendar.end_of_week(2017, 4, 1)
+#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
+```
+
+### Offset fiscal year calendars
+Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that is offset of
+the traditional retail calendar. The `MerchCalendar::FiscalYearCalendar` class allows you to easily
+offset the start of year to match your fiscal calendar.
+
+```ruby
+fiscal_calendar = MerchCalendar::FiscalYearCalendar.new
+
+# 52 or 53 (depending on leap year)
+fiscal_calendar.weeks_in_year(2017)
+# => 52
+fiscal_calendar.weeks_in_year(2018)
+# => 53
+
# get the start date of a given merch week
-MerchCalendar.start_of_week(2017, 4, 1)
-# => #<Date: 2017-04-02 ((2457846j,0s,0n),+0s,2299161j)>
+fiscal_calendar.start_of_week(2017, 1, 1)
+# => #<Date: 2016-07-31 ((2457601j,0s,0n),+0s,2299161j)>
# get the end date of a given merch week
-MerchCalendar.end_of_week(2017, 4, 1)
-# => #<Date: 2017-04-08 ((2457852j,0s,0n),+0s,2299161j)>
+fiscal_calendar.end_of_week(2017, 4, 1)
+#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
```
## Documentation
You can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).
-
-
-## Roadmap
-* Support for 4-4-5 calendars
## License
MerchCalendar is released under the [MIT License](http://www.opensource.org/licenses/MIT).