Skip to content

Commit

Permalink
Update READMEs
Browse files Browse the repository at this point in the history
  • Loading branch information
@elsom25
elsom25 committed May 2, 2024
1 parent da90a9a commit 274ecd6
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 57 deletions.
70 changes: 38 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
<p align="center"><img src="./docs/assets/img/header.png" /></p>

<p align="center"><em><b>This is the development branch</b>. See <a href="https://github.com/Shopify/product-taxonomy/tree/releases"><code>releases</code></a> for stable distribution files.</em></p>

<!-- omit in toc -->
<h1 align="center">Shopify's Standard Product Taxonomy <a href="./VERSION"><img src="https://img.shields.io/badge/version-vUNRELEASED-orange.svg" alt="Version"></a></h1>
<h1 align="center">Shopify's Standard Product Taxonomy <img src="https://img.shields.io/badge/preview-orange.svg" alt="Preview"> <a href="./VERSION"><img src="https://img.shields.io/badge/version-vUNRELEASED-orange.svg" alt="Version"></a></h1>

**🌍 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.

<p align="right"><em>Learn more on <a href="https://help.shopify.com/manual/products/details/product-category">help.shopify.com</a></em></p>

Expand All @@ -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

Expand All @@ -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!

Expand All @@ -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
Expand All @@ -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

Expand Down
34 changes: 9 additions & 25 deletions dist/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,13 @@
<p align="center"><img src="../docs/assets/img/header.png" /></p>

<p align="center"><em><b>This is the releases branch</b>. See <a href="https://github.com/Shopify/product-taxonomy/"><code>main</code></a> for the source.</em></p>

<!-- omit in toc -->
<h1 align="center">Shopify's Standard Product Taxonomy <img src="https://img.shields.io/badge/preview-orange.svg" alt="Preview"> <a href="./VERSION"><img src="https://img.shields.io/badge/version-v0.15.0-blue.svg" alt="Version"></a></h1>

<h1 align="center">Shopify's Standard Product Taxonomy <img src="https://img.shields.io/badge/preview-orange.svg" alt="Preview"> <a href="../VERSION"><img src="https://img.shields.io/badge/version-v0.17.0-blue.svg" alt="Version"></a></h1>

**🌍 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.

<p align="right"><em>Learn more on <a href="https://help.shopify.com/manual/products/details/product-category">help.shopify.com</a></em></p>

Expand All @@ -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!

0 comments on commit 274ecd6

Please sign in to comment.