# Entries and revisions

An entry's page, how revisions go from draft to review to published, why published revisions never change, and upgrading projects.

Source: https://rack-maker.cbnsndwch.dev/docs/catalog/entries-and-revisions

## An entry's page

Every catalog entry has a page at `/catalog/e/<namespace>/<slug>`, for example [/catalog/e/cbnsndwch/shelf-10in](https://rack-maker.cbnsndwch.dev/catalog/e/cbnsndwch/shelf-10in). Open it from a card in [the catalog](https://rack-maker.cbnsndwch.dev/catalog).

The page shows:

- The entry's name, with its id and category beside it (and **hidden** if a moderator has hidden it; see [Reports](https://rack-maker.cbnsndwch.dev/docs/catalog/reports)).
- Its description and, for a device made in the device modeler, a link to the maker's datasheet.
- A 3D preview of the part with its default values.
- Its revisions, newest first. Select a revision to preview it instead.
- **Model file**: the licence and credits of the 3D file it is drawn from, if any.
- **Where to get it**: shops and stores that sell it, with their latest price and stock report.
- **Definition**: the full entry as JSON, with its revision number and licence.

![The catalog page of a device, NAS Box: its id and category, its description, a 3D preview, and its revisions: rev 3 a draft with Edit, Submit and Delete, and revs 2 and 1 published](https://rack-maker.cbnsndwch.dev/docs/shots/catalog/entry-light.webp)

*An entry's page, with a draft of its next revision.*

When you are signed in, the page also offers:

| Button                | Who sees it                                                                 | What it does                                                                                                     |
| --------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Edit measurements** | anyone signed in, on a device made in the device modeler                    | opens the entry in the [device modeler](https://rack-maker.cbnsndwch.dev/docs/modeler)                                                           |
| **New revision**      | whoever may draft in the entry's namespace, when no draft or review is open | starts a new draft from the published revision                                                                   |
| **Fork to @you**      | everyone else                                                               | copies the entry into your namespace as a new draft; see [Namespaces](https://rack-maker.cbnsndwch.dev/docs/catalog/namespaces#copying-an-entry) |
| **Report**            | anyone signed in                                                            | tells the moderators something is wrong; see [Reports](https://rack-maker.cbnsndwch.dev/docs/catalog/reports)                                    |

## Revisions

An entry is a series of numbered revisions: rev 1, rev 2, and so on. Each revision goes through the same steps:

1. **Draft**: private to its author. You can edit it, delete it, and use it in your own projects right away.
2. **Review**: submitted, waiting for someone who may publish it. It can't be edited any more.
3. **Published**: in the catalog for everyone. It never changes again.

A reviewer can also reject a revision. A rejected revision is kept, read-only. To try again, start a new revision.

### Drafts

On an entry's page, each draft of yours has **Edit**, **Submit** and **Delete**. **Edit** opens it in the [catalog editor](https://rack-maker.cbnsndwch.dev/docs/catalog/authoring) (or use **Edit measurements** for a device from the modeler). Nobody else sees your drafts, except the site's admins.

A new draft always takes the next number after every revision of that entry, whatever its status. So if rev 3 was rejected, the next draft is rev 4.

### Submitting

**Submit** (or **Submit for review** in the catalog editor) sends the draft for review. The first time you submit anything, you are asked to agree that your catalog contributions are published under CC BY-SA 4.0. See [Licences and credits](https://rack-maker.cbnsndwch.dev/docs/catalog/licences-and-credits).

An assembly can only be submitted when every entry it uses exists in the catalog.

### Review

Who may approve a revision:

- the owner of the namespace, if they have [contributor access](https://rack-maker.cbnsndwch.dev/docs/catalog/contributing) (owners may approve their own revisions);
- the namespace's maintainers, if they have contributor access;
- the site's admins, for any namespace.

So a contributor publishes in their own namespace by submitting and then approving. Without contributor access, what you submit waits for an admin.

Reviewers find waiting revisions in the **Review queue** on [the catalog page](https://rack-maker.cbnsndwch.dev/catalog), in the **Pending work** panel. Each row links to the entry and has **Approve** and **Reject**. The same buttons appear on the revision's row on the entry's page.

![The Pending work panel with the Review queue: a submitted revision with Approve and Reject buttons](https://rack-maker.cbnsndwch.dev/docs/shots/catalog/work-rail-light.webp)

*The review queue, in the Pending work panel.*

- **Approve** publishes the revision. It becomes the revision the catalog offers, and projects that use an older one are offered the upgrade.
- **Reject** sends it back to its author as rejected.

A device submitted from the device modeler without contributor access carries only its measurements. When it is approved, the approver's browser builds its model file and attaches it.

## Published revisions never change

Once published, a revision is fixed for good. Changing an entry always means a new revision. This is what lets projects rely on the catalog: every part in a project points at an exact revision (`alice/mini-pc-tray` rev 2, say), so a project looks and checks the same tomorrow as it does today, whatever the entry's author does next.

## Upgrades in your projects

When a newer revision of a part your project uses is published, the project offers the upgrade. An **Updates available** card lists each such part with the revisions (for example `rev 1 → 2`) and how many are in use.

- **Preview** shows what the upgrade would change in this project: parameter defaults that move, checks that change between pass and fail, and problems that would appear or go away.
- **Upgrade** moves every use of that part to the new revision.
- **Upgrade all** appears when there is more than one update.

Nothing upgrades on its own, and an upgrade can be undone like any other edit. For more on checks and problems, see [Checks](https://rack-maker.cbnsndwch.dev/docs/editor/checks).

![The Updates available card in a project, with the preview of an upgrade open: the parameter defaults that change, and Preview, Upgrade and Upgrade all](https://rack-maker.cbnsndwch.dev/docs/shots/catalog/upgrade-preview-light.webp)

*Previewing an upgrade before you apply it.*