{"id":19446076,"url":"https://github.com/stitchfix/merch_calendar","last_synced_at":"2025-07-16T23:35:36.397Z","repository":{"id":31616640,"uuid":"35181680","full_name":"stitchfix/merch_calendar","owner":"stitchfix","description":"Calculations around the National Retail Federation's 4-5-4 calendar","archived":false,"fork":false,"pushed_at":"2025-04-01T14:26:59.000Z","size":172,"stargazers_count":14,"open_issues_count":22,"forks_count":5,"subscribers_count":117,"default_branch":"main","last_synced_at":"2025-04-01T15:39:06.893Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stitchfix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-06T20:39:04.000Z","updated_at":"2025-04-01T14:26:50.000Z","dependencies_parsed_at":"2023-02-10T12:31:33.261Z","dependency_job_id":"756d10dd-59ba-4efd-8223-a2ba0245aa64","html_url":"https://github.com/stitchfix/merch_calendar","commit_stats":{"total_commits":167,"total_committers":10,"mean_commits":16.7,"dds":0.5449101796407185,"last_synced_commit":"f4690719900e0179cc843957ab2111c2d3949bd2"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stitchfix%2Fmerch_calendar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stitchfix%2Fmerch_calendar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stitchfix%2Fmerch_calendar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stitchfix%2Fmerch_calendar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stitchfix","download_url":"https://codeload.github.com/stitchfix/merch_calendar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246927835,"owners_count":20856198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T16:12:49.772Z","updated_at":"2025-04-03T03:11:28.224Z","avatar_url":"https://github.com/stitchfix.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Merch Calendar\n\n[![Gem Version](https://badge.fury.io/rb/merch_calendar.svg)](http://badge.fury.io/rb/merch_calendar)\n[![Build Status](https://travis-ci.org/stitchfix/merch_calendar.svg?branch=master)](https://travis-ci.org/stitchfix/merch_calendar)\n[![Code Climate](https://codeclimate.com/github/stitchfix/merch_calendar/badges/gpa.svg)](https://codeclimate.com/github/stitchfix/merch_calendar)\n[![Coverage Status](https://coveralls.io/repos/stitchfix/merch_calendar/badge.svg)](https://coveralls.io/r/stitchfix/merch_calendar)\n\nThis gem allows for finding retail/merchandising weeks for a given date, along with manipulating the retail calendar. \nThis gem is used at [Stitch Fix](http://www.stitchfix.com/).\n\n## Installation\n\n```bash\n$ gem install merch_calendar\n```\n\nAdd the following line to your `Gemfile`:\n```ruby\ngem \"merch_calendar\"\n```\n\n## Ruby Version Compatibility\nThis gem has been tested against Ruby 2.0 - 2.4.\n\nSupport 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 \ninstall the gem like so:\n\n```ruby\ngem \"merch_calendar\", \"0.3.0\"\n```\n\n## Usage\n\nFor converting a date into a `MerchWeek` object.\n\n```ruby\nmerch_week = MerchCalendar::MerchWeek.from_date(\"2014-01-01\", calendar: MerchCalendar::RetailCalendar.new)\n\nmerch_week.year                 # 2013 (the merch year associated with this date)\nmerch_week.month                # 12 (the julian month that the date falls in)\nmerch_week.week                 # 5 (the week number within the month)\nmerch_week.year_week            # 48 (the week number within the retail calendar year)\nmerch_week.quarter              # 4\n\nmerch_week.start_of_week        # \u003cDate: 2013-12-29\u003e\nmerch_week.end_of_week          # \u003cDate: 2014-01-04\u003e\n\nmerch_week.start_of_month       # \u003cDate: 2013-12-01\u003e\nmerch_week.end_of_month         # \u003cDate: 2014-01-04\u003e\n\nmerch_week.start_of_year        # \u003cDate: 2013-02-03\u003e\nmerch_week.end_of_year          # \u003cDate: 2014-02-01\u003e\n\nmerch_week.calendar             # \u003cMerchCalendar::RetailCalendar\u003e (the calendar we're using)\n                                # if you don't initialize a calendar, it defaults to RetailCalendar\n\n# Formatting\nmerch_week.to_s                 # \"Dec W5\"\nmerch_week.to_s(:short)         # \"Dec W5\"\nmerch_week.to_s(:long)          # \"2013:48 Dec W5\"\nmerch_week.to_s(:elasticsearch) # \"2013-12w05\"\n```\n\n\n### Merch retail calendar\n\nRetail calendars have their first month in February, and the last (12th) month is in January of the\nfollowing year.\n\n```ruby\n# This is asking \"In the Merch year of 2014, what is the Gregorian calendar date of\n# the start of the first month?\"\nretail_calendar = MerchCalendar::RetailCalendar.new\n\nretail_calendar.start_of_month(2014, 1)\n# =\u003e 2014-02-02\n\nretail_calendar.start_of_month(2014, 12)\n# =\u003e 2015-01-04\n```\n\nThis table should describe the progression of dates:\n\n| N   |  `start_of_month(2014, N)` |\n| ------------- | ------------- |\n| 1   | 2014-02-02 |\n| 2   | 2014-03-02 |\n| 3   | 2014-04-06 |\n| 4   | 2014-05-04 |\n| 5   | 2014-06-01 |\n| 6   | 2014-07-06 |\n| 7   | 2014-08-03 |\n| 8   | 2014-08-31 |\n| 9   | 2014-10-05 |\n| 10  | 2014-11-02 |\n| 11  | 2014-11-30 |\n| 12  | 2015-01-04 |\n\n\nOther useful methods:\n\n```ruby\n# 52 or 53 (depending on leap year)\nretail_calendar.weeks_in_year(2016)\n# =\u003e 52\nretail_calendar.weeks_in_year(2017)\n# =\u003e 53\n\n# get the start date of a given merch week\nretail_calendar.start_of_week(2017, 4, 1)\n# =\u003e #\u003cDate: 2017-04-30 ((2457874j,0s,0n),+0s,2299161j)\u003e\n\n# get the end date of a given merch week\nretail_calendar.end_of_week(2017, 4, 1)\n#=\u003e #\u003cDate: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)\u003e\n```\n\n### Stitch Fix Fiscal Year Calendars\nSome companies, one of which being Stitch Fix, operate on a fiscal year calendar that instead starts in August \nrather than in February in a the traditional retail calendar.  The `MerchCalendar::StitchFixFiscalYearCalendar` class \nallows you to easily translate Gregorian dates to a Stitch Fix Fiscal Year date.\n\n```ruby\nfiscal_calendar = MerchCalendar::StitchFixFiscalYearCalendar.new\n\nfiscal_calendar.weeks_in_year(2018)\n# =\u003e 52\nfiscal_calendar.weeks_in_year(2019)\n# =\u003e 53\n\n# get the start date of a given merch week\nfiscal_calendar.start_of_week(2017, 1, 1)\n# =\u003e #\u003cDate: 2016-07-31 ((2457601j,0s,0n),+0s,2299161j)\u003e\n\n# get the end date of a given merch week\nfiscal_calendar.end_of_week(2017, 4, 1)\n#=\u003e #\u003cDate: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)\u003e\n```\n\n#### Stitch Fix Fiscal Year Calendar in Relation to MerchWeek object\nYou can set MerchWeek object respond to the Stitch Fix Fiscal Calendar, by passing in `StitchFixFiscalYearCalendar.new` in the calendar parameter:\n\n```ruby\nmerch_week = MerchCalendar::MerchWeek.from_date(\"2018-07-02\", calendar: MerchCalendar::StitchFixFiscalYearCalendar.new)\n\nmerch_week.year                 # 2018 (the merch year associated with this date)\nmerch_week.month                # 7 (the julian month that the date falls in)\nmerch_week.merch_month          # 12 (this fiscal month the date falls in)\nmerch_week.week                 # 1 (the week number within the month)\nmerch_week.year_week            # 49 (the week number within the retail calendar year)\nmerch_week.quarter              # 4\n\nmerch_week.start_of_week        # \u003cDate: 2018-07-01\u003e\nmerch_week.end_of_week          # \u003cDate: 2018-07-07\u003e\n\nmerch_week.start_of_month       # \u003cDate: 2018-07-01\u003e\nmerch_week.end_of_month         # \u003cDate: 2018-07-28\u003e\n\nmerch_week.start_of_year        # \u003cDate: 2017-07-30\u003e\nmerch_week.end_of_year          # \u003cDate: 2018-07-28\u003e\n\nmerch_week.calendar             # \u003cMerchCalendar::StitchFixFiscalYearCalendar\u003e (the calendar\n                                # we're using)\n                                # if you don't initialize a calendar, it defaults to RetailCalendar\n\n# Formatting\nmerch_week.to_s                 # \"Jul W1\"\nmerch_week.to_s(:short)         # \"Jul W1\"\nmerch_week.to_s(:long)          # \"2018:49 Jul W1\"\nmerch_week.to_s(:elasticsearch) # \"2018-07w01\"\n```\n\n## Documentation\nYou can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).\n\n## License\nMerchCalendar is released under the [MIT License](http://www.opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstitchfix%2Fmerch_calendar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstitchfix%2Fmerch_calendar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstitchfix%2Fmerch_calendar/lists"}