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:

  1. 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.
  2. 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.
  3. 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

Issue fork governance-3327844

Command icon 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:

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

quietone created an issue. See original summary.

drumm’s picture

This 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:

  1. Convert it to markdown, delete https://www.drupal.org/contribute/core/maintainers and redirect that URL to the Markdown version. So there is one canonical version, no copies to maintain, with the same editing rights.
  2. Migrate it to documentation. 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.
  3. Copy it to a page in a section. Only maintainers & editors of the section will be able to edit it.

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.

xjm’s picture

Why 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.

quietone’s picture

Title: Convert documentation to markdown » Migrating governance docs
Issue summary: View changes

I'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.

xjm’s picture

Hm, #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.

drumm’s picture

Issue summary: View changes

Clarifying 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.

drumm’s picture

Issue summary: View changes

Adding notes about the Drupal revision history

  • Migrate it to documentation: keeps Drupal revision history
  • Copy it to a page in a section: loses it (there may be workarounds, which would take some amount of time)

However, since the canonical version is in Git, the revision history is actually less-important.

drumm’s picture

I 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.

Gábor Hojtsy’s picture

Status: Active » Needs review

I 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?

Dries’s picture

Let'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.

Gábor Hojtsy’s picture

Title: Migrating governance docs » Convert governance docs to markdown, redirect d.o page to Gitlab UI as canonical version

Titling based on the direction then.

quietone’s picture

In 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.

  • 583500f1 committed on master
    Issue #3327844 by quietone, drumm, xjm, Gábor Hojtsy, Dries: Convert...
Gábor Hojtsy’s picture

Thanks, 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?

Gábor Hojtsy’s picture

This also resolved #2962251: Smart Quotes and  's "accidentally", so bringing in @mgifford's credit here.

Gábor Hojtsy’s picture

Worked 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.

drumm’s picture

The 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.

Gábor Hojtsy’s picture

My 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?

Gábor Hojtsy’s picture

Ok #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.

quietone’s picture

Just 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

  • (General) Community Communication Strategy
  • Documentation Guidelines, Policies, and Standards
  • Documentation Working Group Goals, Priorities, and Projects
  • Drupal Documentation Logos
  • Many Drupal Community Working Group Meeting
  • Many Drupal Technical Working Group Meeting Minutes
  • Drupal.org Advisory Group
  • Drupal 8 Accelerate Fund
  • D8 Accelerate Sprint planning

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?

hestenet’s picture

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?

From a technical point of view, I don't think anything prevents making an archive documentation section on Drupal.org for this.

drumm’s picture

The 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"

Gábor Hojtsy’s picture

Priority: Normal » Major

Added 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.

drumm’s picture

I 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

Gábor Hojtsy’s picture

Issue summary: View changes
FileSize
196.05 KB

https://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 :)

Gábor Hojtsy’s picture

Status: Needs review » Reviewed & tested by the community
drumm’s picture

Done 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

Gábor Hojtsy’s picture

I 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.

quietone’s picture

Issue summary: View changes

Nice, this is so close to being finished!

This link is different than the one suggested in #27.

https://www.drupal.org/governance/docwg-charter --> https://git.drupalcode.org/project/governance/-/blob/main/charters/docum...

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.

Gábor Hojtsy’s picture

Status: Reviewed & tested by the community » Needs work

I 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 :)

Gábor Hojtsy’s picture

Status: Needs work » Fixed

1. 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!

quietone’s picture

Lovely. Glad to see this finished. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.