Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Problem/Motivation
I've offered to migrate the governance docs to the new system but want to be sure where they should go and who can edit them. Right now, the edit access is restricted. And that in itself is the likely cause of 4 issues sitting at RTBC for an extended time, 1 or 5 years and 3 for 3 years. Should that change?
Steps to reproduce
Proposed resolution
There are 3 possible resolutions:
- Convert it to markdown, delete https://www.drupal.org/contribute/core/maintainers and redirect that URL to the canonical Markdown version at https://git.drupalcode.org/project/governance. So there is one canonical version, no copies to maintain, with the same editing rights.
- Migrate it to documentation. The Drupal revision history is kept. All confirmed users on Drupal.org will be able to edit it. Maintainers of the documentation guide it lands in can be notified of edits.
- Copy it to a page in a section. The Drupal revision history is lost. Only maintainers & editors of the section will be able to edit it.
Remaining tasks
Create redircts
Note that the MR is a conversion of the docs to Markdown.
User interface changes
API changes
Data model changes
Comment | File | Size | Author |
---|---|---|---|
#26 | Screenshot 2023-08-07 at 9.58.39.png | 196.05 KB | Gábor Hojtsy |
#12 | convert_html_to_markdown.php_.txt | 1.02 KB | quietone |
Issue fork governance-3327844
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
drummThis came up for migrating https://www.drupal.org/contribute/core/maintainers from a book page to something else. All book pages need to be off of Drupal.org to help unblock upgrading Drupal.org.
There are 3 possible resolutions:
Since we have GitLab rendering Markdown now, that’s a quick way of making the document readable by people, and sidestepping any migration, keeping the edit access the same as who has access to push to the repository.
Comment #3
xjmWhy can't we use the "Full HTML" workaround to prevent editing by the masses?
I mean markdown would be nice, but I don't want us to get blocked on a markdown support issue.
Comment #4
quietone CreditAttribution: quietone at PreviousNext commentedI've moved the nice options by drumm to the issue summary and updated the title.
In Slack, lauriii said that they did not have a strong preference but wants to avoid option 2.
As for myself, the current edit strategy is not working so either #2 or #3.
Comment #5
xjmHm, #4 makes me think we need some clarification. I assumed that these would still be copies of the official governance repo. If we want to actually change the policy so that core committers can update their own governance, we'd need Dries' signoff for that. Like it would actually be a governance change to allow us to improve our own governance docs.
Comment #6
drummClarifying Markdown support is in GitLab, we’d link to the canonical version on https://git.drupalcode.org/project/governance, when/if it exists in Markdown format that’s readable.
Comment #7
drummAdding notes about the Drupal revision history
However, since the canonical version is in Git, the revision history is actually less-important.
Comment #8
drummI did forget about the "Full HTML" workaround. It is a workaround and not a perfect option, but can be combined with “Migrate it to documentation”. I would like to remove it someday, but that’s nowhere near on the horizon. 103 people currently can edit Full HTML, which is too many, but that’s another issue.
Comment #9
Gábor HojtsyI think having it in Markdown in the repo is the best for avoiding duplication. The reason they are not edited currently is not technical but rather a governance question. The git version will retain edit history and also it was/is the canonical version. I think it will also clarify how its modified, which is good. I myself wanted to fix up something in the governance docs, because the double presentation of it was not clear to me.
Question is how do we make it discoverable that way? Is there a solution for that? Link it in from various places and hope people find it? The googleability will be quite different, no?
Comment #10
Dries CreditAttribution: Dries commentedLet's go with Markdown in Gitlab. Good suggestion, @drumm.
Markdown seems easiest as the documents have been converted already, it maintains the governance, and it unblocks the migration work.
The only downside is that non-technical users could be confused by all the Gitlab related navigation and nomenclature that will surround the documents. I don't believe that to be a deal-breaker.
A special thank you to @quietone for converting the documents! I appreciate the help.
Comment #11
Gábor HojtsyTitling based on the direction then.
Comment #12
quietone CreditAttribution: quietone at PreviousNext commentedIn slack @Gábor Hojtsy asked how I converted the files which I will answer here for the record.
I wrote a PHP script that used HTML To Markdown for PHP. I doubt that I would have made additional changes because this should just be a straight conversion. And I don't recall making any, even for formatting or spelling.
Comment #14
Gábor HojtsyThanks, I committed these changes. While I was there, I also renamed the master branch to main, especially since we are about to make links and redirects to this.
I think there are two or three remaining questions here:
- Would be great to have a README.md that is displayed right away and provides an index to the repository. I can create one that lists all the files in the repo, is that what we wanted? That would make this page a lot more friendly: https://git.drupalcode.org/project/governance
- Should the values and principles doc that is currently in the repo stay here? That has its own separate page at https://www.drupal.org/about/values-and-principles, if this is the canonical version, probably this one should stay and that one should be redirected?
- If that is the values and pricinples page to stay rather than the repo, should we rename the drupal-code.md to README.md or include a separate index given all the content about the working groups?
Comment #16
Gábor HojtsyThis also resolved #2962251: Smart Quotes and 's "accidentally", so bringing in @mgifford's credit here.
Comment #17
Gábor HojtsyWorked on #3348734: Make governance index page available as index page of git repo to also reproduce the index page of the governance structure in this repo. That serves as a guide to the files in the repo and now links to all the repos. It has the hierarchy tables from https://www.drupal.org/governance display as actual graphs :)
(For those that don't have admin access to this repo, they would see less distracting things).
With this in place, @drumm asked for an index of links from/to to redirect. I don't think this is entirely clear cut yet still. Here is my working list:
Straightforward moves:
https://www.drupal.org/governance --> https://git.drupalcode.org/project/governance/
https://www.drupal.org/contribute/core/maintainers --> https://git.drupalcode.org/project/governance/-/blob/main/drupal-core.md
Values and principles is at an entirely different place, yet maintained as source in this rep, so if we want to keep this one as definite, then:
https://www.drupal.org/about/values-and-principles --> https://git.drupalcode.org/project/governance/-/blob/main/values-and-pri...
This, but the doc working group has a bunch more content in this book, those should move elsewhere?
https://www.drupal.org/governance/docwg-charter --> https://git.drupalcode.org/project/governance/-/blob/main/charters/docum...
This, but the list of members and contact process need to be moved to the charter first:
https://www.drupal.org/governance/licensing-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/licen...
This, but the list of members and contact process need to be moved to the charter first:
https://www.drupal.org/governance/security-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/secur...
This, but the list of members and contact process need to be moved to the charter first, also this has other pages in the book that need to move?
https://www.drupal.org/governance/technical-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/techn...
+ the Governance book has other pages that are not in the repo, such as a Drupal.org Advisory Group that I think is defunct, a General Community Communication Strategy, specifically a page on Announcements Feed governance, pages on the Drupal 8 Accelerate Fund, etc.
Comment #18
drummThe governance repo doesn’t need to, and probably shouldn’t, contain everything relating to governance. Everything should be migrated somewhere, but it doesn’t all have to be to one place.
The repo should be reserved for anything that needs a formal approval process by the central governance. A repository is too much infrastructure for anything else.
In general, I recommend allowing editing by as many people as practical. If something is okay to be edited by anyone in the Drupal Community, it should be a documentation guide/page. People can follow documentation pages to get notified about changes, so if someone makes a bad edit, it can be caught and corrected. If something should be edited only by a limited number of people, a section and pages are the right thing to use. The more people that can edit something, the more chance there is that someone might keep it up to date.
We have tooling to migrate book pages to documentation with keeping the edit history. We do not have this for sections and pages; those will be made new, old pages deleted, and replaced with redirects to the new pages.
For example, https://www.drupal.org/community/cwg is a section maintained by members of the Community Working Group. They can easily update policies and everything there; there’s no need for that group’s policies to go through a Git repository.
A section for each active working group is probably a good place to start.
Comment #19
Gábor HojtsyMy understanding was keeping it in git will be the most transparent for the community in terms of when and how it changes. Also it seemed simpler as an immediate solution. I think we can revisit that later if the git version proves to be ineffective.
Opened #3349898: Merge member lists and contact info for working groups to git repo to sync the member list and contact info as per #17 above for the 3 affected charters. That would AFAIS allow to remove and redirect those 3 pages too, then the only thing left is to find a place for the rest of the pages that are not in the git repo, but I don't know where would they go. Per @drumm, @quietone had suggestions already?
Comment #20
Gábor HojtsyOk #3349898: Merge member lists and contact info for working groups to git repo landed now. So the only blocker to put the redirect in place in #17 I think are moving the pages that are not in the repo.
Comment #21
quietone CreditAttribution: quietone at PreviousNext commentedJust working to see what pages need to move.
Governance for Drupal Announcements feed - This stays in the repo
I think these are the titles of the pages to move
The community working group section has a version of the charter, https://www.drupal.org/community/cwg
Made an issue for moving the old CWG minutes #3363114: Move old CWG minutes
The more I think about the pages that need to move, I think a sensible way to do this is to just make an archive section. Is that possible?
Comment #22
hestenetFrom a technical point of view, I don't think anything prevents making an archive documentation section on Drupal.org for this.
Comment #23
drummThe overall technical goal is we need zero book content type nodes on Drupal.org, so they do not have to be migrated to modern Drupal. As long as they are migrated away from that content type, they can be labeled anything, including "archive"
Comment #24
Gábor HojtsyAdded a comment on #3363114: Move old CWG minutes, is there a way we can escalate this with the CWG? How can we move forward with the rest of the items? For example, I landed #3059388: Officially replace the title BDFL with Project Lead and other changes recently but it is not really effective until the redirects are in place since the d.o pages still have a copy of the old governance text.
Comment #25
drummI think https://www.drupal.org/governance/drupalorg-advisory-group can be deleted since it went along with the outdated Drupal.org working group information that got deleted. If we want to credit people, making a role so it can be listed on user profiles https://www.drupal.org/community/contributor-guide/find-your-role is best for this
Comment #26
Gábor Hojtsyhttps://www.drupal.org/community/contributor-guide/find-your-role is meant to represent current roles, not historic roles AFAIS. I deleted https://www.drupal.org/governance/drupalorg-advisory-group
I also moved over the TWG meeting minutes from 2016 to the coding standards project. Only one of the minutes had attendance info, credited the people there. For the rest i credited the original node author.
The only remaining "unrelated" subsection of the governance tree are the DocWG pages. I contacted Joe Shindelar about those :)
Comment #27
Gábor Hojtsy@eojthebrave moved the docwg subpages, so we are all good to go to add the redirects and remove the old pages.
https://www.drupal.org/governance --> https://git.drupalcode.org/project/governance/
https://www.drupal.org/contribute/core/maintainers --> https://git.drupalcode.org/project/governance/-/blob/main/drupal-core.md
https://www.drupal.org/governance/docwg-charter --> https://git.drupalcode.org/project/governance/-/blob/main/charters/docum...
https://www.drupal.org/governance/licensing-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/licen...
https://www.drupal.org/governance/security-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/secur...
https://www.drupal.org/governance/technical-working-group --> https://git.drupalcode.org/project/governance/-/blob/main/charters/techn...
----
Followup: Values and principles is at an entirely different place, yet maintained as source in the git repo, so if we want to keep this one as definite, then we should discuss https://www.drupal.org/about/values-and-principles vs https://git.drupalcode.org/project/governance/-/blob/main/values-and-pri... in a follow up too. That does not relate to the governance doc structure though, so not blocking here.
Moving to RTBC for setting up those redirects and removing those pages.
Comment #28
drummDone except for https://www.drupal.org/governance and one last straggler that was hidden in inaccessible book navigation.
https://www.drupal.org/governance/core/initiatives, which is linked to from https://www.drupal.org/about/core/strategic-initiatives. I expect should be migrated somewhere under https://www.drupal.org/about/core
Comment #29
Gábor HojtsyI straight up added the content of that page to the bottom of https://www.drupal.org/about/core/strategic-initiatives, it was a short page. So I think https://www.drupal.org/governance/core/initiatives could be removed and redirected to https://www.drupal.org/about/core/strategic-initiatives :) and the parent governance page can also be removed and redirected to the main page of the git repo.
Comment #30
quietone CreditAttribution: quietone at PreviousNext commentedNice, this is so close to being finished!
This link is different than the one suggested in #27.
This one goes to https://www.drupal.org/docs/working-group/documentation-working-group-ch... not https://git.drupalcode.org/project/governance/-/blob/main/charters/docum...
Does that need to be changed?
I am going to set to Needs Work for that question and #29.
Comment #31
Gábor HojtsyI think #30 is because the doc migration tool was used and that set up a redirect. I discussed with Joe to not have the governance copy there either, since there is one canonical place for it in the repo. I think the https://www.drupal.org/docs/working-group/documentation-working-group-ch... page should also be removed and redirected. And the redirect to that removed and instead going to the git version at https://git.drupalcode.org/project/governance/-/blob/main/charters/docum...
So this needs work and #29 needs work :) But we are indeed super close :)
Comment #33
Gábor Hojtsy1. Updated governance/docwg-charter to redirect to https://git.drupalcode.org/project/governance/-/blob/main/charters/docum... instead of https://www.drupal.org/docs/working-group/documentation-working-group-ch...
2. Removed https://www.drupal.org/docs/working-group/documentation-working-group-ch... and redirected it to https://git.drupalcode.org/project/governance/-/blob/main/charters/docum... too, even though it was a short lived page (and is not linked from the (new) docwg guide).
3. Removed https://www.drupal.org/governance/core/initiatives and redirected the path to https://www.drupal.org/about/core/strategic-initiatives where I copied its contents before.
4. Removed https://www.drupal.org/governance and added a redirect to https://git.drupalcode.org/project/governance/-/blob/main/README.md
I think this is finally fully done. Thanks all!
Comment #34
quietone CreditAttribution: quietone at PreviousNext commentedLovely. Glad to see this finished. Thanks!