simple Draft/Review/Release workflow

[tvogt]

Describe the feature you'd like

A simple workflow to mark a specific revision of a page as "current/official/released" with further edits of the page indicating a "draft" status.

Only specified users can change the released revision. By default the released revision is displayed to readers, even if newer revisions exist. Edits start at the latest revision (no branching support required)

Describe the benefits this would bring to existing BookStack users

Allows the usage of BookStack for internal documentation and company handbooks which are closer to a release process than a wiki process in nature.

My specific use case: I'd like to propose BookStack for use as the internal company handbook tool. We could start without such a feature, but eventually down the line the question will appear.

Can the goal of this request already be achieved via other means?

No, because while a workflow status could be achived with tags, there is no functionality to show not the current revision of a page, but a specially-marked one.

Issue https://github.com/BookStackApp/BookStack/issues/1686 would if implemented possibly allow this feature in a different way, but it is likely much more complex than this request.

Have you searched for an existing open/closed issue?

• [X] I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

Not using yet, just scoping

Additional context

Wikipedia has such as system in the Flagged Revisions extension. Confluence has a similar feature as an app in https://marketplace.atlassian.com/apps/1216387/approvals-for-confluence?tab=overview&hosting=cloud

[ssddanbrown]

Thanks for the input @tvogt. This also has overlap with existing open issue #473.

I'm apprehensive about going down this path though, since BookStack is primarily focused on a live "living docs" usage and this kind of addition primarily opens the platform up for new usages, rather than strengthening existing use-cases, although there will be some overlap in this.

This addition of adding multiple states starts to complicate things quite considerably in terms of what users expect to see and access, especially so when you layer on existing and intended mechanisms such as the current user-level drafts and future long-term-intent for multi-language support.

Just trying to really boil down your requirement to its fundamentals. It sounds to me like so: The core need is to have controlled/approved outputs to an audience from a source that can be continuously edited without affecting that controlled/approved output.

Is that a fair reduction of this request? If so:

• What audience are you primarily looking to use BookStack for? The viewers reading the controlled/approved outputs or the editors of content?
• At what level, for your use-case, would you see approvals/publishings primarily occurring at? Would this generally occur across a Book or would it need to be more granular?

[tvogt]

@ssddanbrown even a "living docs" needs to have a kind of "this is the approved version" thingy in most business contexts. Several standards (such as ISO27001, ISO9001, etc.) explicitly require this.

All that's really needed is one boolean field on the page data that says "approved" and one setting in the roles that limits which role(s) can approve pages. The only tricky part is that the code needs to show not the latest version, but the latest approved version when displaying a page for reading, while showing a different (the latest) version when opening for editing. At least that's how I would code it. I don't think branches etc. are required at all. It might be useful to have a button to switch to reading the latest not-approved version, but that's optional.

I can't say what the "primary" audience is. I'm thinking of both readers (who want to know that what they're reading is the official docs, not a work-in-progress) and editors (who want to edit and revise in a kind of "draft" mode). I'm also thinking of managers who want to approve things before they become official (they may not even be editors themselves).

In my mental model, approvals happen at the page level. IMHO the page is the atomic unit in BookStack and thus this is where it makes sense. Everything else would make things a lot more difficult, wouldn't it?

Unlike #473 I'm not looking for a full (or configurable) workflow. Only a single toggle.

Unlike #2725 I don't want any support for multiple versions (branches) of a page, merging, etc. nor would I want that the owner of a page is the approver.

---

Background:

Almost everything that is in any way regulated by any standard requires that documents have an approval step and that a reader can see if he is reading the official/current version of the document. Words like "approval" appear all over ISO 27001 and its chapters on documentation, for example. It doesn't need to be complicated or anything. There just needs to be something that says "this is approved".

I'd like to use BookStack for the internal documentation on ISO27001 projects. Both my own company and recommend it as a Free Software and easy-to-used solution to customers whom we are supporting in such projects. It has everything else that the standard requires (access controls, versioning, meta information), except this.

Maybe it would be easier if I make a fork and show what I want with code instead of words?

[ssddanbrown]

Thanks for the extra context. I'm going to close this in favour of #473. Although the requested implementations differ I feel the core requirement overlaps, and I try to focus on base requirements in these issues.

even a "living docs" needs to have a kind of "this is the approved version" thingy in most business contexts

Maybe, but the only evidence I have of requirement is user demand, and there has been relatively little demand for this so far and is not a necessity for existing users.

All that's really needed is one boolean field on the page data that says "approved" and one setting in the roles that limits which role(s) can approve pages.

It will not be that straightforward. Changing the system to exactly match your requested implementation may not be too much effort but implementing a solution that does not affect existing workflows/usage will be more complex. Additionally, the expectations of how such a system would behave would likely differ for other users/companies. At the current time, I would not deem the added complexity worthwhile.

Maybe it would be easier if I make a fork and show what I want with code instead of words?

I understand your request, I was just trying to boil it down to it's fundemental needs so we're not distracted by specific implementation ideas.

[JasperE84]

Almost everything that is in any way regulated by any standard requires that documents have an approval step and that a reader can see if he is reading the official/current version of the document.

This exactly is the main thing I'd also like to see a solution for. Allow edits by the existing permission structure (ldap groups integrated in my case) and extend it with a workflow of approval of those edits by another permission level (read, edit, create, delete and approve)

[deelite]

I am currently reviewing various solutions for our in-house documentation. Either they are too expensive at tens of thousands of Euros or too much expansion is required to get the desired solution. Bookstack has been the favorite so far. However, we are dependent on a review/approval process, so we are stuck at this point. My opinion is that these requirements should become more important in the enterprise environment. After all, the support contracts suitable for business users already exist.

Is the implementation perhaps already in planning and is it foreseeable to be able to use a review/approval process in the near future? We could certainly do without it for some time.

[ssddanbrown]

@deelite

Is the implementation perhaps already in planning and is it foreseeable to be able to use a review/approval process in the near future?

No, although I don't plan too far ahead to be honest. It's in my mind though, and I'm working on other bits that I'd see as a precursor to this like #4371 and comment improvements.

My opinion is that these requirements should become more important in the enterprise environment.

I'm sure they are more important in the enterprise space, but I prioritise the existing BookStack audience and use-cases over chasing wider audiences or potential other use-cases.

---

If you have any PHP dev skills in-house, or available, you may be able to make use of our logical theme system to jerry-rig some level workflow/process, or use that, or webhooks, along with an external platform to suit your requirements.