Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhance PageRevision to include release notes #24

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+54 −0
Open

Enhance PageRevision to include release notes #24

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4e4c222
Add RFC 019
kutenai Mar 29, 2018
188b94d
Update rfc from 19 to 23
kutenai Apr 30, 2018
1c6edaa
Rename files and remove RFC number
kutenai Apr 30, 2018
c543d21
Update with some additional thoughts on UX
kutenai Apr 30, 2018
ae31ce6
Update to assigned RFC number
kutenai Apr 30, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions text/024-revision-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# RFC 24: Release Notes on Revisions

* RFC: 24
* Author: Edward Henderson
* Status: Draft
* Created: 2018-03-29
* Last Modified: 2018-04-30

## Abstract

Enhance the revision system to allow release notes to be added when publishing.

## Specification

The current revision system is great, but does not offer a way to provide release
notes for a revision. This RFC proposes that the mechanism be expanded to allow a custom release model to be used for a page, and a way to override the publish dialog to support addition of release notes.

### User Experience

Adding comments for a draft should be optional, but allowed. I could see a simple option, possibly with a keyboard enabler, such as Control+Click on Save Draft will show
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Control+Click sounds like a big issue from an accessibility point of view. Given there's already a dropdown over the Save button showing additional options, it would probably make sense to leverage the same mechanism (a Save with comment option maybe?).

a comments dialog. Another option would be make comments be a page specific option, so they are turned on/off for a page

### Editing Notes

One appraoch here would be to allow editing revision notes in the Settings panel. I don't think this should be a "required" option, but more of a optional one, enabled
in configuraiton.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the idea here would be to be able to see all the notes without having to navigate to the specific pages, in other words, a centralised location for notes?

Also, why the settings panel? I can't really think of revisions notes as settings. Is the intent to hide it from the main view?


If notes are part of the UI, then they should be paged, since it would be possible to have many notes.

Also, if notes are captured during draft mode, they should be consolidated and condensed during release, so there would only be draft notes betwween publishes, and all drafts would be combined into the publish notes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's an interesting idea. You would probably need some human intervention though as it is possible to "revert" one or more draft by selecting a previous one. The automatic consolidation would probably pick up notes from discarded drafts.


### Tagging Revisions

This was not part of my original idea. I don't personally see a need to tag revisions, since I assume that revisions are a linear history of a given page.


## Open Questions

### Should revision history be collected for Draft revisions?

I can see that it might be important to capture notes for a draft release, and then combine those notes into a published release.
If each draft offers the ability to add a note for the release, then a publish could then combine the notes from the drafts created since the last release, into
a single release note.

I do not suggest anything very fancy here. Limit the release notes to simle text, or, at best text with Markdown support that can be rendered later. This
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would imagine simple text to be enough, but if we need rich text, we should leverage draftail instead of pushing for Markdown. As a developer I love Markdown, but this would be a confusing experience to regular user of the CMS.

format would be easy to work with, and easy to concatenate all notes from a list of "drafts".

### Should this enhancement replace current functionality?

I would suggest an "alternate" Revision model, that could be conigured in settings. This maintains the existing behaviour, but allows for an option to specify
a new PageRevision model. The core of wagtail could offere multiple such model, and users would be able to provide their own.

Custom models would require some ability to specify UI updates