Plant Releases and Approval

Submit committed plant changes for review, have a named reviewer approve them, merge them as a numbered revision, and make that revision effective on the floor, now or at a time you pick.

Quality systems like ISO 9001 ask for a named person to approve each change before it reaches production, and a record of who asked, who approved and when. In Threaded, plant changes reach the floor branch (main) only through a release: an editor submits what was committed, a reviewer they name approves or rejects it, and once it’s approved an editor merges it, much like a pull request on GitHub. Each merged release gets a revision number, Rev 1, Rev 2 and so on, that an auditor can ask about.

#What it is

  • Release submits a commit on the working branch (dev) for review, with a Name, a Reason for change and a Reviewer. Nothing reaches the floor branch yet.
  • Review shows the reviewer exactly what the release would merge: the changed files with their diffs, the commits included and the plant’s checks. The page works these out from git each time it opens, so they’re always current.
  • Approve records the reviewer’s decision: who approved it, when, and their comment. Nothing moves yet. Reject records the reviewer’s comment, and nothing is merged.
  • Merge puts the approved change on the plant’s main branch as the next revision and imports it into Run. It isn’t on the floor until it’s made effective. Any Owner or Editor can merge an approved release: usually the person who submitted it, when they’re ready.
  • Make effective is the deploy step: from that moment, new work orders use the revision, and work orders that haven’t started move to it. Make it effective now, or schedule it for a date and time, like Monday’s shift change. Each change is recorded with who made it, when, why, and which work orders moved.
  • Releases, in the side menu between Plant and Run, lists every release with its revision and status. It’s shown to Owners and Editors.
Commit ──▶ dev ──Release──▶ In review ──Approve──▶ Approved ──Merge──▶ Merged (Rev N) ──Import──▶ Ready ──Make effective──▶ Effective (the floor)
                                     └─Reject──▶ Rejected                                                  └─Schedule──▶ Scheduled ──at its time──▶ Effective
Any open release (In review or Approved) ──a new release is submitted──▶ Replaced
Effective ──a newer revision is made effective──▶ Superseded ──Make effective again──▶ Effective (a rollback)

An owner can turn off Require approval to merge in Admin › Approvals. Then a release in review can be merged straight away, without an approval, and naming a reviewer is optional.

Approving and merging are separate steps, and neither changes the floor. The floor keeps running its revision until someone makes the new one effective. See Make a revision effective.

#Rules

  • Only Owners and Editors can submit, review and see releases. Floor, Operator and View All members can’t.
  • By default a release must be approved before it can be merged (Require approval to merge in Admin › Approvals). An owner can turn it off: then any Owner or Editor can merge a release that’s still in review, and the Reviewer is optional. Leave it on when a second person must sign off, as ISO 9001 asks: a release merged without approval names no approver.
  • The reviewer must be an Owner or Editor.
  • The reviewer can’t be the person who submitted the release, unless an owner turns on Allow self-approval in Admin › Approvals. Leave it off when a second person must sign off. A one-person organization that isn’t certified yet can turn it on.
  • Only the requested reviewer can approve or reject. A release submitted with no reviewer (while approval wasn’t required) can be approved or rejected by any Owner or Editor once approval is required again, so it isn’t stuck; the person who submitted it can approve it only with Allow self-approval on. Its page and the Releases banner say it needs an approval from any editor.
  • Any Owner or Editor can merge an approved release. Merging your own approved release needs no setting: that’s the point of approving first.
  • Changing Require approval to merge applies at once: turned back on, a release still in review needs its approval before it can be merged.
  • A release is blocked while the plant at its commit has errors. Warnings don’t block it. The checks run again when it’s merged.
  • One release is open at a time: in review, or approved and not merged yet. Submitting a new one replaces it, and the old one shows Replaced. Replacing an approved release drops its approval, so the new one needs its own.
  • A merge that is already running still lands. If a new release replaces this one in the moment while it merges, it still shows Merged with its revision, and the new release stays in review.
  • Merging puts exactly what the page showed on main. If the floor branch moved while you were looking, the merge is refused and nothing is merged: review again.
  • main changes only through a merged release. There is no direct push.
  • Approving and rejecting both need a comment.
  • Only an imported revision (Ready) can be made effective, and only by an Owner or Editor. The AI assistant can’t.
  • One change can be scheduled at a time. To schedule another, reschedule or cancel the waiting one first. While one is scheduled, Make effective now is refused too.
  • Going back to an older revision is a rollback and needs a reason. It doesn’t need a new approval: that revision was approved when it was merged.
  • An approval can’t be withdrawn. If the reviewer finds a problem after approving, the submitter submits a new release, which replaces the approved one and needs its own approval.

#In the app

#Submit a release

Commit your changes in Plant first. Then open Releases in the side menu and click New release, much like opening a pull request. If Plant last saw uncommitted changes in your workspace, the page says they won’t be in this release, with a Commit button.

Fill in:

  1. Name: one line saying what the release changes.
  2. Reason for change: why you’re making this change. Reviewers and auditors read this, and quality systems like ISO 9001 ask for it. It starts empty. Add commit notes adds the commits’ notes as a list, if you want them; the commits are on the release either way.
  3. Reviewer, in the steps card on the right: an Owner or Editor. If there’s only one, it’s picked for you. When your organization requires no approval, this reads Reviewer (optional) and nobody is picked for you: leave it empty, or name someone if you’d like a review anyway.

Under the form, three tabs show what you’re submitting:

  • Commits: everything committed since the last release, newest first, with what it follows (2 commits since Rev 7 (MFG-0018 Fixes the image)). To release only part of the working branch, click Include up to here on an older commit. Newer commits stay on the working branch for a later release. Include all commits goes back to the newest commit.
  • Checks: whether the plant passes plantformat’s checks at that commit, with any errors and warnings. A dot on the tab shows how they went: green when they pass, amber with warnings, red when they fail. With warnings or errors, the tab also shows how many, such as Checks 2. Errors block Submit for review; warnings don’t.
  • Files changed: each changed file with its diff.

Click Submit for review (Submit, when no approval is required) under the reviewer, or Cancel to go back to Releases. Nothing is merged until it’s approved (or, with no approval required, until someone clicks Merge), and the floor doesn’t change until the merged revision is made effective. The page then opens the release’s review page. If you switch away and come back, the page reads the release again and keeps what you typed. If someone committed in the meantime, the page still shows (and submits) the commits you were looking at, and says how many new commits there are. Click Include to add them to this release.

The reviewer gets a notification in Threaded, on their phone if they use the app, and by email. Each one names the release and who submitted it, and links to the review page; the email also quotes the start of the reason. If you name yourself as the reviewer (with Allow self-approval on), no notification is sent.

#Review a release

Open the release from the notification you were sent, from Releases in the side menu, or from the banner at the top of that page. The release’s page shows its name and status. On the right, a steps card lists Submit, Approve, Merge and Make effective, with who did each and when, and marks the step the release is waiting on. The one thing to do next sits under the steps: Approve and Reject for the reviewer, Merge once it’s approved, or Make effective… once it’s merged and imported. New release shows the same card, with the reviewer and Submit for review.

  • Conversation: the release’s story. The reason comes first, as the submitter’s opening post. Then come the approval or rejection with the reviewer’s comment, the merge and its revision, and, once it’s merged, whether the floor runs it now or it’s ready to make effective.
  • Commits, Checks (✓, ✕, or ⚠ with the number of warnings) and Files changed: what the release holds. While it’s open (in review, or approved and not merged), these are worked out from git each time the page opens, against main now, so they show exactly what merging would send. Once it’s decided, they show what it held then, against the release it followed. If the plant repository can’t be reached, the page says so and keeps the Conversation.

The page reads the release again when you come back to it, so there’s no Refresh button.

  • If people committed more since the release was submitted, the page says N newer commits on the working branch are not in this release. The submitter can click Submit the newest instead to submit a new release that replaces this one.
  • Try it first, under the steps card, opens Plant’s Map in Trial mode on the release’s plant, exactly as it was submitted, so you can run units through it before approving or merging. Owners and Editors can run a trial of a release while it’s open (in review or approved). The trial is a mode of its own. In place of Plant’s tabs, the toolbar reads Trial run of release with its summary and commit, and says it’s read-only. The plant picker, the Trial run switch, Code and Commit are hidden, and nothing you do in the trial is saved. You can start orders, complete units at each station, view a station as its operator, and open a station’s instructions; an instruction’s station link goes back to the map. Your own work in the workspace is left as it is. Click Back to review to leave the trial and return to the release.

If you’re the requested reviewer, the steps card has Approve and Reject (anyone else sees who it’s waiting on):

  • Approve opens Approve and the release’s name. It says what you’re approving: how many commits, how many files changed, whether the checks pass, and the commit the approval covers (newer commits aren’t covered). Write an Approval comment (it’s required, as for a rejection), then click Approve. Your comment is saved on the release with your name and the time. Nothing is merged yet, and the floor doesn’t change until the release is made effective.
  • Reject… asks what needs to change. The submitter sees your comment on the release.

#Merge an approved release

Once a release is approved, the steps card shows Merge to every Owner and Editor. The tabs still show what merging sends, worked out from git, so you can check nothing changed since the approval.

When your organization requires no approval, Merge is in the steps card while the release is still in review, and the Approve step says Not required (or that the reviewer you named can review). A reviewer you named can still approve or reject it first.

Click Merge. Threaded squashes the release onto main as the next revision (the revision is taken when it’s merged, so revisions follow the order releases reach main) and starts the import into Run. While the import runs, or if it fails, the page says so at the top. Once it’s done, the Conversation says Rev N is imported into Run and ready to make effective.

#Make a revision effective

Making a revision effective is the deploy step. From that moment:

  • New work orders use it.
  • Work orders that haven’t started move to it, to the end of their first station’s Up next. One whose part isn’t on the new revision stays behind and can’t start until you fix it.
  • Started work orders keep running on the revision they started on, until they finish.
  • Run › Instructions and the floor map show it.

Once a merged release is imported (Ready), its page’s steps card shows Make effective… to Owners and Editors. Before that, it says you can make it effective once the import is Ready. Releases › Effectivity lists every imported revision, and any Ready or Superseded one has Make effective… there too.

Make effective… opens a confirmation that shows what changes before anything moves:

  • When: Now, or Later. You pick the date and time in your own time zone, which is shown under the field, and it suggests tomorrow at 06:00. If Admin › Plant calendar sets the plant to a different time zone, the confirmation also says what that time is on the plant clock, so a shift change lands when you mean it to.
  • What changes: the revision the floor goes from and to, and the releases that brings in (or, going back, takes back out), each linked to its page.
  • Work orders: how many that haven’t started will move, how many can’t move because their part isn’t on the new revision, and how many started ones keep running on the current revision.
  • Files changed since the current revision, with their diffs. If the plant repository can’t be reached, it says so; each release’s own page still has its changes.
  • Reason: saved with the change, with your name and the time. It’s required to go back to an older revision.

Click Make effective or Schedule. If someone changed the floor’s revision while the confirmation was open, it’s refused and nothing moves: open it again to see the new state.

Scheduled changes. A scheduled change shows Scheduled in the list, on the release’s steps card and on Releases › Effectivity, with who scheduled it. Reschedule… moves it to another time (the history keeps who moved it and the time it was first planned for); Cancel scheduled change drops it, and the floor stays where it is. At its time, Threaded makes it effective. If the floor’s revision changed after it was scheduled (someone made another revision effective, or Make effective when merged did), it doesn’t apply: it fails, the floor stays where it is, and it shows in the history. Whoever scheduled it and the release’s submitter get a notification in Threaded and by email when a scheduled change applies or fails.

Going back. A release whose revision the floor has moved past shows Superseded, and its page offers Make effective again…. That’s a rollback: it needs a reason, and the work orders that haven’t started move back to it like any other change.

Make effective when merged. An owner can turn this on in Admin › Approvals. A release merged through Releases then becomes effective as soon as its import is Ready, with no separate step. A commit pushed to main without a reviewed release isn’t made effective this way. Each switch is still recorded, as automatic.

#Effectivity

Releases has two views, switched at the top: Releases (the list below) and Effectivity, which says what the floor runs.

Effectivity has:

  • On the floor, on the right: the revision the floor runs, since when and who made it effective, and a scheduled change with Reschedule… and Cancel scheduled change. It also says when Make effective when merged is on.
  • Revisions: every imported commit, with its status, how many open work orders still run on it, and Make effective…, Retry import or Re-import. See Releases › Effectivity.
  • History: every change of the floor’s revision, newest first, for auditors. Each row has When it happened (when it applied, when it was cancelled, or, for a failed change, when it was due), What happened (Made effective, Rollback, Automatic, Failed or Cancelled), From → to with each release linked, Who (and who cancelled or rescheduled it), the Reason (or why it failed), and Work orders: how many moved and how many were left behind. Click the count to list them. Pick From and To dates, or one kind of change from the What happened column’s header (for example Rollback), to narrow it. Times, and the days From and To pick, are in your own time zone. Export CSV downloads exactly what’s shown, with the same columns plus each commit’s full SHA and the change’s ID, and writes each time with its zone. A reason that starts with =, +, - or @ is written with a leading ', so a spreadsheet shows it as text instead of running it.

#The Releases page

When people have committed changes that aren’t in a release yet, a panel at the top of Releases says how many (3 commits not in a release), whether the plant passes its checks, and how many warnings it has (warnings don’t block a release). It lists the newest of those commits with who made them and when. Commits the open release already includes aren’t counted: they’re listed below, under Already in that release (in review, or approved and waiting to merge), with a link to it. Click New release to release the rest; that replaces the open release with one that includes everything. It’s hidden when nothing is waiting, or when the open release already includes the newest commit.

Releases lists every release, newest first, with Name (its MFG number and name), Rev (the revision number, once merged), Status, Submitted and Reviewed. The release’s commit is on its review page. The open release is a banner at the top: Waiting on the reviewer with Open review, Approved by the reviewer with Merge, or, when no approval is required, No approval needed · ready to merge (or Ready to merge · {reviewer} can still review, if you named one) with Merge. Search by name, reason, the reviewer’s comment, who submitted, reviewed or merged it, MFG number (MFG-0027 or 27), revision (Rev 3), or the start of its commit (the one released, or the one it made on the floor branch). Filter from the Status column’s header: All, Open (in review, or approved and waiting to be merged), Merged or Rejected. The header shows the one picked (Status: Merged), and the search and the filter work together. Statuses:

  • In review: waiting on the reviewer.
  • Approved: approved, waiting for an editor to merge it.
  • Merged: on main as its revision, not effective yet. On a release merged without an approval, the Approve step says Not required.
  • Scheduled: merged, with a change waiting to make it effective at a set time.
  • Effective: the revision the floor runs now.
  • Superseded: a revision the floor has moved past.
  • Rejected: the reviewer said no. Their comment is on the release.
  • Replaced: a newer release was submitted before this one was merged.

Every release is named with its number in front, like MFG-0027 Adding a sharpening station: you type the name, and the release takes the organization’s next number when you submit it. Actions take theirs from the same sequence, so if a release is MFG-0002 the next action is MFG-0003, and a release never takes a number an existing action already has. Existing actions keep their numbers. A rejected or replaced release keeps its number. The number is also the headline of the release’s commit on the floor branch. Rev is different: it counts merged releases only (Rev 1, Rev 2, …).

#Admin › Approvals

Only Owners can open this page and change the organization’s approval rules. Under Plant releases:

  • Require approval to merge: a reviewer must approve each release before anyone can merge it. It’s on by default. Turn it off to merge without a sign-off, for example while a small team isn’t certified yet.
  • Allow self-approval lets the person who submits a release also approve it. It’s off by default, and only applies while an approval is required.
  • Make effective when merged makes a release merged through Releases effective on the floor as soon as its import is Ready. It’s off by default.

#Troubleshooting

The Reviewer list is empty. No one else in your organization is an Owner or Editor. Add another editor in Admin › People, or ask an owner to turn on Allow self-approval, or turn off Require approval to merge, in Admin › Approvals.

Merge says only an approved release can be merged. Your organization requires an approval to merge. Ask the reviewer to approve it, or ask an owner whether an approval should be required.

Merge says another release was merged first. The floor branch moved while you were looking. Click Refresh, check the changes again, then merge.

Merge says the release is no longer waiting to be merged. Someone else merged it, or a new release replaced it. Click Refresh to see which.

The review says this release can’t be merged. Its changes are already on the floor branch, a newer release went out first, or its commit is no longer on the working branch. Submit a new release.

The review says the plant did not pass its checks. Fix the errors in Plant, commit, and submit a new release.

Make effective… is greyed out, or missing. The release’s import into Run isn’t Ready yet, or it failed. The top of the page says which; see Plant Git and Imports.

Make effective says another change is scheduled. Only one can wait at a time. Reschedule or cancel it from Releases › Effectivity or its release’s page.

A scheduled change didn’t apply. The floor’s revision changed after it was scheduled, so it no longer made sense. The history on Releases › Effectivity says why. Schedule it again if you still want it.

The review can’t show the changes. Threaded couldn’t reach your plant repository. Click Retry in a moment. Approve and Merge stay off until the changes show.

#Audit trail

Each merged release’s commit on main names who submitted, approved and merged it in git trailers, so the record travels with the repository. The person who merged it is the commit’s author.

Threaded-Revision: 15
Threaded-Submitted-By: <who submitted it>
Threaded-Approved-By: <who approved it>
Threaded-Merged-By: <who merged it>
Threaded-Release-Request: prq-…
Threaded-Dev-Sha: <the commit on dev it released>

A release merged without an approval (when the organization doesn’t require one) has no Threaded-Approved-By line.

Releases merged before approving and merging were separate steps have Threaded-Released-By: <who submitted it> instead of the Submitted-By and Merged-By lines; their approver merged them. Threaded reads both forms.

Rejected, replaced and approved-but-not-merged releases are kept in Threaded, with who decided and when.

Every change of the floor’s revision is recorded in Threaded: the revision it went to and from, whether it was made effective now, scheduled, a rollback or automatic, who decided and when, the reason, and each work order that moved or stayed behind. Cancelled and failed scheduled changes are kept too. The records can’t be edited or deleted, from the app or by Threaded’s admins; deleting the whole organization is the only thing that removes them. Export CSV on Releases › Effectivity gives an auditor the history for any date range.

#API

run_format_plant_release_requests_list lists releases (filter with status: one status, or open for in review and approved), run_format_plant_release_requests_retrieve reads one with its live review, run_format_plant_release_requests_create submits one, run_format_plant_release_requests_approve and run_format_plant_release_requests_reject decide one, and run_format_plant_release_requests_merge merges an approved one (or one in review, when the organization requires no approval; requestedReviewerUuid is then optional on create). For the floor’s revision: run_format_plant_effectivity_retrieve reads On the floor, run_format_plant_effectivity_revisions_list lists the imported revisions (filter with status: all, ready or failed), run_format_plant_effectivity_history_list lists the history (since and until dates) and run_format_plant_effectivity_history_export returns it as CSV, run_format_plant_effectivity_changes_retrieve reads one change with its work orders, run_format_plant_effectivity_preview shows what making a revision effective would change, run_format_plant_effectivity_changes_create makes one effective now or schedules it, and run_format_plant_effectivity_changes_reschedule and run_format_plant_effectivity_changes_cancel change a scheduled one. They all need a person signed in as an Owner or Editor. API tokens and the AI assistant can’t use them.