From 274ecd68090b0ba66bb73209a2fdcdc64029f302 Mon Sep 17 00:00:00 2001 From: Jesse McGinnis Date: Wed, 1 May 2024 23:54:59 -0400 Subject: [PATCH] Update READMEs --- README.md | 70 +++++++++++++++++++++++++++----------------------- dist/README.md | 34 +++++++----------------- 2 files changed, 47 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 2fcddd2b..37abdd15 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,13 @@

-

This is the development branch. See releases for stable distribution files.

- -

Shopify's Standard Product Taxonomy Version

+

Shopify's Standard Product Taxonomy Preview Version

**🌍 Global Standard**: Our open-source, standardized product taxonomy establishes a universal language for product classification. Comprehensive and already empowering merchants on Shopify. **👩đŸŧ‍đŸ’ģ Integration Friendly**: With a stable structure and diverse formats our taxonomy is designed for effortless integration into any system. -**🚀 Industry Benchmark**: Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. +**🚀 Industry Benchmark**: Spanning 25+ essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces.

Learn more on help.shopify.com

@@ -25,18 +23,17 @@ - [đŸ¤ŋ Diving in](#-diving-in) - [🛠ī¸ Setup and dependencies](#ī¸-setup-and-dependencies) - [📂 How this is all organized](#-how-this-is-all-organized) +- [🧑‍đŸ’ģ Contributing](#-contributing) - [📅 Releases](#-releases) - [📜 License](#-license) ## 🕹ī¸ Interactive explorer -Ready to dive in? [Explore our taxonomy interactively](https://shopify.github.io/product-taxonomy/releases/unstable/?categoryId=gid%3A%2F%2Fshopify%2FTaxonomy%2FCategory%2Fsg-4-17-2-17) to visualize and discover what's published across the many categories, attributes, and values. +Ready to dive in? [Explore our taxonomy interactively](https://shopify.github.io/product-taxonomy/releases/unstable/?categoryId=gid%3A%2F%2Fshopify%2FTaxonomyCategory%2Fsg-4-17-2-17) to visualize and discover what's published across the many categories, attributes, and values. ## 📚 Taxonomy overview -Our taxonomy is an open-source comprehensive, global standard for product classification. It's a universal language that empowers merchants to categorize their products. Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. - -What's next? ⏭ī¸ More attributes and values as we work to make this truly comprehensive. +Our taxonomy is an open-source comprehensive, global standard for product classification. It's a universal language that empowers merchants to categorize their products. Spanning 25+ essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. ## 🧭 Getting started @@ -46,7 +43,7 @@ We've structured it to be as user-friendly as possible, whether you're looking t ### 🧩 How to integrate with the taxonomy -Dive straight into [`releases` branch](https://github.com/Shopify/product-taxonomy/tree/releases) to find the files you need and integrate this taxonomy into your system. +Dive straight into [`dist`](./dist/) to find the files you need and integrate this taxonomy into your system. We're working on a variety of formats to make it easy to integrate with your systems. Today we have `txt` and `json` formats, and we're working on more. If you have a specific format you'd like to see, please open an issue and let us know! @@ -58,20 +55,20 @@ Everything comes from the source-of-truth files in [`data/`](./data). This is wh ### 👩đŸŧ‍đŸ’ģ How to evolve the system -This system is how we manage the taxonomy and generate distributions. This is where the magic happens. +Everything else is how we manage the taxonomy and generate distributions. This is where the magic happens. ## đŸ¤ŋ Diving in -This is a simple ruby app with a few models and serializers. The bulk of the work is parsing `data/` into a tree of `app/models/category.rb` to serialize reliably to `/dist/`. The app is setup to be rails-like, but is not a rails app, though is using `ActiveRecord`. +This is a simple ruby app with a few models and serializers. The bulk of the work is parsing `data/` into a tree of `app/models/category.rb` to serialize reliably to `dist/`. The app is set up to be rails-like including using `ActiveRecord`. Everything ultimately runs through `make` (`dev` simply proxies). Here are the commands you'll use most often: ```sh make [build] # build the dist and documentation files make clean # remove sentinels and all generated files -make seed # parse /data into local db +make seed # parse data/ into local db make test # run ruby tests and cue schema verification -make server # http://localhost:4000 interactive view of /dist/ +make server # http://localhost:4000 interactive view of dist/ ``` ## 🛠ī¸ Setup and dependencies @@ -92,43 +89,52 @@ When you edit any cue files, ensure you're running `cue fmt`. This will format t Most folks won't touch most of this, but we see you 👩đŸŧ‍đŸ’ģ. If you want to add a new serialization target, three simple steps: -1. Add a new serializer to `app/serializers` -2. Add the file load to `application.rb` -3. Extend `bin/generate_dist` to use your new serializer and write files +1. Add a new serializer to `app/serializers/dist/` +2. Extend `bin/generate_dist` to use your new serializer and write files -For your own explorations, here's a map of the land: +For your explorations, here's a map of the land: ``` ./ -├── application.rb # handles file loading "app-wide" -├── Makefile # primary source of useful commands -├── Rakefile # only used for testing +├── application.rb # handles file loading "app-wide" +├── Makefile # primary source of useful commands +├── Rakefile # only used for testing ├── app/ │ ├── models/ # most models are simple data objects -│ │ ├── category.rb # node-based tree impl for categories +│ │ ├── category.rb # node-based tree impl for categories │ │ └── ... │ └── serializers/ -│ ├── data/ # object-centric, to read/write source-data files -| ├── data/ # object-centric, for docs site -│ └── dist/ # file-type-centric, for dist files -│ ├── json.rb -│ └── text.rb +│ ├── source_data/ # object-centric, to read/write source-data files +│ ├── docs/ # object-centric, for docs site +│ └── dist/ # file-type-centric, one file per distribution type ├── bin/ -│ ├── generate_dist # file IO for /data → /dist -│ └── generate_docs # file IO for /dist → /docs +│ ├── generate_dist # primary entrypoint for generating dist/ +│ └── generate_docs # primary entrypoint for generating docs/ ├── db/ -│ ├── schema.rb # defines in-memory tables for models -│ └── seed.rb # seed the db by parsing data shaped from /data +│ ├── schema.rb # defines tables for models +│ └── seed.rb # seed the db by parsing data shaped from data/ +├── data/ +│ ├── integrations/ # integrations and mappings between taxonomies +│ ├── localizations/ # localizations for categories, attributes, and values +│ ├── categories/ # source-of-truth for categories +│ ├── attributes.yml # source-of-truth for attributes +│ └── values.yml # source-of-truth for values └── test/ ``` +## 🧑‍đŸ’ģ Contributing + +We welcome contributions! Before we can merge any changes you submit, you'll need to sign the Shopify CLA (a friendly robot will help when you open your first PR 🤖). + ## 📅 Releases -You can always find the current published version in [`VERSION`](./VERSION). The changelog is available in [`CHANGELOG.md`](./CHANGELOG.md). +You can always find the current published version in [`VERSION`](./VERSION). The changelog is available in [`CHANGELOG.md`](./CHANGELOG.md). While this is `UNSTABLE`, we're using SemVer, but when this goes stable it will transition to [CalVer](https://calver.org/), in sync with [Shopify's API release schedule](https://shopify.dev/docs/api/usage/versioning#release-schedule). -That means a stable release every 3 months **at most**, at the beginning of the quarter. Version names are date-based to be meaningful and semantically unambiguous (for example, `2024-01`). +That means a stable release every 3 months **at most**, at the beginning of the quarter. Version names are date-based to be meaningful and semantically unambiguous (for example, `2024-07`). + +Formal releases are published as Github releases and available on the [interactive docs site](https://shopify.github.io/product-taxonomy/). ## 📜 License diff --git a/dist/README.md b/dist/README.md index f5faba07..f6af51c9 100644 --- a/dist/README.md +++ b/dist/README.md @@ -1,16 +1,13 @@

-

This is the releases branch. See main for the source.

- -

Shopify's Standard Product Taxonomy Preview Version

- +

Shopify's Standard Product Taxonomy Preview Version

**🌍 Global Standard**: Our open-source, standardized product taxonomy establishes a universal language for product classification. Comprehensive and already empowering merchants on Shopify. **👩đŸŧ‍đŸ’ģ Integration Friendly**: With a stable structure and diverse formats our taxonomy is designed for effortless integration into any system. -**🚀 Industry Benchmark**: Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. +**🚀 Industry Benchmark**: Spanning 25+ essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces.

Learn more on help.shopify.com

@@ -19,44 +16,31 @@ - [🕹ī¸ Interactive explorer](#ī¸-interactive-explorer) - [📚 Taxonomy overview](#-taxonomy-overview) -- [🧭 Getting started](#-getting-started) - [🧩 How to integrate with the taxonomy](#-how-to-integrate-with-the-taxonomy) - - [🧑đŸŧ‍đŸĢ How to make changes to the taxonomy or system](#-how-to-make-changes-to-the-taxonomy-or-system) + - [👀 Everything else?](#-everything-else) - [📅 Releases](#-releases) - [📜 License](#-license) ## 🕹ī¸ Interactive explorer -Ready to dive in? [Explore our taxonomy interactively](https://shopify.github.io/product-taxonomy/releases/unstable/?categoryId=gid%3A%2F%2Fshopify%2FTaxonomy%2FCategory%2Fsg-4-17-2-17) to visualize and discover what's published across the many categories, attributes, and values. +Ready to dive in? [Explore our taxonomy interactively](https://shopify.github.io/product-taxonomy/releases/unstable/?categoryId=gid%3A%2F%2Fshopify%2FTaxonomyCategory%2Fsg-4-17-2-17) to visualize and discover what's published across the many categories, attributes, and values. ## 📚 Taxonomy overview -Our taxonomy is an open-source comprehensive, global standard for product classification. It's a universal language that empowers merchants to categorize their products. Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. - -What's next? ⏭ī¸ More attributes and values as we work to make this truly comprehensive. - -## 🧭 Getting started - -This repository is the home of Shopify's Standard Product Taxonomy. It houses the source-of-truth data, the distribution files for implementation, and the source code that makes this all sing. - -We've structured it to be as user-friendly as possible, whether you're looking to integrate the taxonomy into your system, suggest changes, or delve into how it's developed and maintained. +Our taxonomy is an open-source comprehensive, global standard for product classification. It's a universal language that empowers merchants to categorize their products. Spanning 25+ essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces. ### 🧩 How to integrate with the taxonomy We're working on a variety of formats to make it easy to integrate with your systems. Today we have `txt` and `json` formats, and we're working on more. If you have a specific format you'd like to see, please open an issue and let us know! -### 🧑đŸŧ‍đŸĢ How to make changes to the taxonomy or system +### 👀 Everything else? -Dive straight into the [`main` branch](https://github.com/Shopify/product-taxonomy/tree/main) to modify the soure-of-truth data or the code that generates the taxonomy. +Hop back to root and check out the main [`README.md`](../README.md). Go forth and explore! ## 📅 Releases -You can always find the current published version in [`VERSION`](./VERSION). The changelog is available in [`CHANGELOG.md`](./CHANGELOG.md). - -While this is `UNSTABLE`, we're using SemVer, but when this goes stable it will transition to [CalVer](https://calver.org/), in sync with [Shopify's API release schedule](https://shopify.dev/docs/api/usage/versioning#release-schedule). - -That means a stable release every 3 months **at most**, at the beginning of the quarter. Version names are date-based to be meaningful and semantically unambiguous (for example, `2024-01`). +You can always find the current published version in [`VERSION`](../VERSION). The changelog is available in [`CHANGELOG.md`](../CHANGELOG.md). ## 📜 License -Shopify's Product Taxonomy is released under the [MIT License](./LICENSE). So go ahead, explore, play, and build something awesome! +Shopify's Product Taxonomy is released under the [MIT License](../LICENSE). So go ahead, explore, play, and build something awesome!