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

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.

Titling based on the direction then.

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.

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 → credited mgifford → .

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

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.

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.

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?

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.

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?

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.

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"

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.

• https://www.drupal.org/governance/community-working-group/minutes → has been replaced with a redirect to a new page with the same content
• “(General) Community Communication Strategy” was deleted as it was outdated
• https://www.drupal.org/drupalorg/docs/content/governance-for-drupal-anno... → was moved to that new home
• https://www.drupal.org/governance/d8accelerate → has been replaced with a redirect to a new page with the same content and mentioned on https://www.drupal.org/about/core/previous-initiatives →

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

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

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

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 →

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.

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.

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 → credited eojthebrave → .

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!

Lovely. Glad to see this finished. Thanks!

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