Create governance dcoumentation stored in repo/GitLab Pages

Currently the only documentation available regarding the process to adopt a module are located on D.O. in a location where anyone can edit them. This raises questions about the accuracy of the documents at any given moment.

Is there any edit which defaced the documentation page? For what I recall, that never happened.
It is not necessary to move the documentation to GitLab Pages. All the project moderators have the permissions to use the Full HTML format, which cannot be used from people without specific roles.

Is there any edit which defaced the documentation page? F

Your text provides a key concern I have with these pages. It is being described as a "documentation page' not a 'Policy page".

I'm not aware of any deliberate modification to deface the page, although I am aware of lines that may not be written the best as they could be as they use phrases such as "Must" and "will" in a manner that appears to imply these are mandatory non-discretionary steps when other posts by site moderators appear to imply these are general cases, however not mandatory.

Without a formal policy I am unable to ascertain with certainty which of the two interpretations is correct in order to propose documentation edits.

In the past i have tried quoting from the relevant pages and been told these are not policy.

Offering to become a project owner, maintainer, or co-maintainer is not a policy, nor is a documentation page describing the terms of service. Please stop making false claims.

-- https://www.drupal.org/project/drupalorg/issues/3452333#comment-16094934 📌 Automate the majority of the ownership transfer process (retain human approval) Active
The page links both to

https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

At this point I keep receiving conflicting statement a large part of it may be a language barrier with the involved individuals. Having a well defined policy page with a tracked record of every change linked directly to the discussion involved (where not just the text of the policy but the thought process behind the wording is present) would provide more clear context to both understand the policy and to provide references when communications difficulties may be involved.

It is not necessary to move the documentation to GitLab Pages.
While perhaps not 100% necessary it would provide assertions on authenticity.

Drupal Core governance has done this in 📌 Make gitlab pages for governance.drupal.org Active .
The coding standards group is considering the same in 📌 Convert Coding Standards to GitLab pages Active .

I am a fan of governance policies in repo as well

- Tim Lehnen
CTO of the Drupal Association
https://drupal.slack.com/archives/C5ABFBZ5Z/p1746562504563009?thread_ts=...

Nothing of what you describe changes moving the documentation pages in the repository, to which any project maintainer for the Drupal.org project ownership would have access, especially when they are project moderators or have a higher role.

That documentation page has been created time ago to describe what people who wanted to become co-maintainer/maintainer or project owner should do, such which title give to the issue, how long the issue must be kept in the project issue queue before moving it, who can move the issue, what can be changed in the issue after it was created and from who can be changed. It does not say that a project moderator, finding an issue for an offer to become maintainer created the day before, cannot contact the project maintainers.
What the documentation page says does not change moving it to a repository, nor does the nature of that documentation page change because it is moved to a repository.

Nothing of what you describe changes moving the documentation pages in the repository,

My understanding from previous conversations is that the pages are editable by even average users today (I can open the edit page, I have not tried saving to confirm), if so that would change as moving it to the repository.

to which any project maintainer for the Drupal.org project ownership would have access, especially when they are project moderators or have a higher role.

Are you saying we do not have a policy for when the document is allowed to be updated or are you saying that we can't trust the Project Ownership Queue admins to not make make nu-approved changes?

That documentation page has been created time ago to describe

If we do not think the current page as-is is useful I'm willing to help write something more governance like based on the current documentation published.

Your text provides a key concern I have with these pages. It is being described as a "documentation page' not a 'Policy page".

Even if those documentation pages were rewritten as GitLab pages, that would hold true the same: Those pages do not become policy just because they are moved to GitLab pages.

Without a formal policy I am unable to ascertain with certainty which of the two interpretations is correct in order to propose documentation edits.

The same ambiguity is present in the Drupal coding standards, since they have not been written in legalese and they do not contain a section explaining what shall or other terms mean. Even as GitLab pages, that ambiguity is still present in the Drupal coding standards.

In the past i have tried quoting from the relevant pages and been told these are not policy.

They are not policy.
They have been created to describe what people who wanted to be able to create full projects had to do to get that permission; they have been then updated by project moderators to describe the procedure they were following, what they expected by applicants, and what they expected by reviewers. It has been then changed when people were allowed to create full projects but still needed an extra role to be able to opt projects into security advisory coverage.

Are you saying we do not have a policy for when the document is allowed to be updated or are you saying that we can't trust the Project Ownership Queue admins to not make make un-approved changes?

I am not sure why you keep talking of policy when there are many missing policies on drupal.org, but (to answer) there are three parts which cannot be changed:

• What it is reviewed (a project with commits done from the applicant)
• What is reported (the correct use of Drupal API, code that does not have possible security issues, and the respect of the Drupal coding standards)
• The fact people who offered to become co-maintainers do not automatically get the permission to opt projects into security advisory coverage without applying to get the permission like other people

I am still not clear what this issue is trying to achieve because the issue summary speaks of avoiding everybody can change the current documentation, but then some comments speak of policies (as if there must be policies), and then the last comments speak again of protecting the documentation from "unauthorized" changes.

If the aim is avoiding everybody can edit what reported in the documentation pages, then the fact that those pages are policy is irrelevant to avoid everybody can edit them. If the aim is creating policies, then the fact everybody can edit them is secondary.

In both the cases (avoiding everybody can edit what reported in the documentation pages and creating policies) the solution is not necessarily creating GitLab pages, which at the end is just a possible solution with pros and cons. It is not neither the only solution, nor it is the solution with less cons. (Actually, it is not even the simpler solution.)

If we do not think the current page as-is is useful I'm willing to help write something more governance like based on the current documentation published.

Since the current documentation describes exactly the process to get a specific permission, what applicants need to do, and what reviewers need to do, I do think it is useful.

I am not sure why you keep talking of policy when there are many missing policies on drupal.org,

Exactly the concern this issue is trying address. Just because there is a lack of policy does not mean we shouldn't try and formalize one.

but (to answer) there are three parts which cannot be changed:

Are any of these directly related to project ownership?

I do wish to make it clear, that, baring a written policy that can never be updated everything can be changed, the key issue is who has the authority to make the changes.

I have been discussing a separate D.O. process recently and it has been discovered that there likely is no longer a management process in place for it. Is the same possibly true for Project Ownership, that the D.A. has left no team empowered to make formal policy changes?

Even if those documentation pages were rewritten as GitLab pages, tThose pages do not become policy just because they are moved to GitLab pages.

The issue title and summery make it very clear, this issue is about documenting a formal policy. It is not the necessarily the act of moving to GitLab that does so it is the deceleration that "the following is the policy" that makes the difference.

The same ambiguity is present in the Drupal coding standards, since they have not been written in legalese and they do not contain a section explaining what shall or other terms mean

This issue has proposed correcting that as it relates to the Project Ownership process. It does not necessarily need to be legalese though that does create a more unified writing style, it just needs to not have ambiguity, or at least have an ability to have the governing board be able and willing to update it when ambiguity creates a friction point.

I am still not clear what this issue is trying to achieve because the issue summary speaks of avoiding everybody can change the current documentation,

The issue title is clearly Create governance documentation stored in repo/GitLab Pages the issue summary is background information on why to choose GitLab Pages and why a formal governance policy is needed.

the solution is not necessarily creating GitLab pages, which at the end is just a possible solution with pros and cons. It is not neither the only solution, nor it is the solution with less cons. (Actually, it is not even the simpler solution.)

Would you please enumerate the cons and other solutions you would propose as alternatives.

While I have not responded to every single one line question above I believe I have covered them in the general response above, if more clarification is required do ask.

Exactly the concern this issue is trying address. Just because there is a lack of policy does not mean we shouldn't try and formalize one.

No, this issue is not trying to make a policy. What is trying to achieve is reported in the very first following lines of the issue summary.

Currently the only documentation available regarding the process to adopt a module are located on D.O. in a location where anyone can edit them. This raises questions about the accuracy of the documents at any given moment.

The rest of the issue summary propose a solution, which could eventually avoid everybody can edit those documentation pages, but which is also not the only possible solution, given that the documentation pages are still Drupal nodes.

I do wish to make it clear, that, baring a written policy that can never be updated everything can be changed, the key issue is who has the authority to make the changes.

It is not clear what baring a written policy that can never be updated everything can be changedwould mean, but policies do get updates; they are not written in stone.
As for who has the authority to make changes, that depends on the changes. Changes done to comply with laws are done by the DA; changes done to fix typos or grammar errors are done by everybody; changes done to reflect what the process exactly is are done by project moderators.

it just needs to not have ambiguity, or at least have an ability to have the governing board be able and willing to update it when ambiguity creates a friction point.

English has ambiguities; that cannot be removed.
The DA can make any change to documentation pages about the process followed to appoint project owners, maintainers, or co-maintainers and it is willing to update them when necessary. The DA already updated those pages.

The issue title and summery make it very clear, this issue is about documenting a formal policy.

Again, no, it is not. That could be your intent, but the issue summary is not about creating a policy. I propose the Project Ownership process adopt storing a formal governance document that is stored in the project repository. does not say that a policy needs to be created where no policy exists. It just suggests to use the project repository to store a document. Since a document already exists, that for me means moving a document.

Would you please enumerate the cons and other solutions you would propose as alternatives.

Let me ask these questions.

• Can you list any case where the documentation pages in question have been wrongly changed?
• GitLab pages apart, have you considered other solutions?
• When considering the described solution (hosting documentation on this very project repository), have you considered any pro and con?
• Have you considered any preliminary work necessary to implement the proposed solution?
• Who do you propose should do that preliminary work?
• Given that the proposed solution has been adopted for the Coding standards, do you know any detail about how they proceeded?
• Do you know of other ways to avoid everybody can a set of documentation pages, even in the case that set includes a single page?
• Who should be allowed to edit the documentation in question?

No, this issue is not trying to make a policy. What is trying to achieve is reported in the very first following lines of the issue summary.

I believe we should trust the creator of the issue knows what their intention was and as such accept their word as sufficient of intention. Trying to say I do knot know why this issue was created is disingenuous and disrespectful.

I propose the Project Ownership process adopt storing a formal governance document that is stored in the project repository. does not say that a policy needs to be created where no policy exists.

Simple logical reasoning. A policy to be stored has to either already exist, or would have to be created.

Since a document already exists, that for me means moving a document.

Where does the formal governance document exist? I am not proposing moving the 'guidelines' document.

Let me ask these questions.

I remind you the D.O. CoC requires you to be collaborative, deflecting my questions asking what your concerns are to ask what steps I have done is non-collaborative behavior. I again ask you to enumerate your concerns.

Can you list any case where the documentation pages in question have been wrongly changed?

I will note that you personally brought this up as a concern to me on Slack.

I am aware of at least on incident that involved myself making minor language changes to make the documentation match how project ownership queue admins (especially yourself @avpaderno) actual process requests. The history of this record has since been deleted from the node history, this raises questions about the integrity of the history for making determinations.

Addtionaly in ~2022 @avpaderno you deleted where these pages were originally stored, the Drupal Infrastructure team restored them and you again deleted them. This was at the time considered a significantly disruptive/wrong change. A significant amount of edit history was lost due to this action, and our ability to review the intention of the texts has been lost.

GitLab pages apart, have you considered other solutions?

I have. GitLab provides a robust architecture for discussion so that should any ambiguities occur we can review the exact issue and related discussion to help determine what was the actual intention of the wording was.

When considering the described solution (hosting documentation on this very project repository), have you considered any pro and con?

I have, see all related responses in this section. The most significant con is that pages are not indexed on D.O. and search engines may need some time to discover them, this is easily mitigated by posting the link to the pages on the Project page and the fact that the policy itself is for those of us seeking a more advanced understanding of the process.

I will also note that @hestenet said I am a fan of governance policies in repo as well which is partly what triggered opening this issue. Ref: https://drupal.slack.com/archives/C5ABFBZ5Z/p1746562504563009?thread_ts=...

Have you considered any preliminary work necessary to implement the proposed solution?
Yes. GitLab pages are easy to setup, given we have another repo to copy from templates are already built. There is essentially no preliminary work except identifying the actual policy.

Who do you propose should do that preliminary work?

I volunteered to take the effort if no one else was willing to do so above.

Given that the proposed solution has been adopted for the Coding standards, do you know any detail about how they proceeded?

They had a formal policy document that they could directly copy into the repository. That is lacking here, the best we could do is take the Guide and use it as a baseline to write a formal procedure with singoff from the DA prior to commit.

Do you know of other ways to avoid everybody can a set of documentation pages, even in the case that set includes a single page?

I believe there may be a missing word here and assume the question was "to avoid everyone can edit> a set of..." If not please provide correction and ignore this response:

You have in the past mentioned that changing to FULL HTML as one method. We could also implement custom code in Drupal.org Customization, or otherwise create a specific node type for policy documents. However my understanding from (unrelated) discussion with the Infra team is they prefer to scale down the customization and content types.

It is not clear what baring a written policy that can never be updated everything can be changed would mean, but policies do get updates; they are not written in stone.
As for who has the authority to make changes, that depends on the changes. Changes done to comply with laws are done by the DA; changes done to fix typos or grammar errors are done by everybody; changes done to reflect what the process exactly is are done by project moderators.

It was you arguing that we could not make certain changes. I was mentioning that unless there is a charter (that is prohibited from being changed or itself prohibits making changes) that was not a factually valid statement.

Who should be allowed to edit the documentation in question?

How governance document changes are made should be a basic part of any governance policy and depends on the structure. Generally since these are 'formal documents' they would generally not permit arbitrary edits without a formal process (such as a majority vote of those authorized to make the changes agreeing the change should be made). Think of these as similar to 'bylaws amendments'.

I believe we should trust the creator of the issue knows what their intention was and as such accept their word as sufficient of intention. Trying to say I do knot know why this issue was created is disingenuous and disrespectful.

The intention must be explicit stated in the issue summary. It cannot be implicit.

I remind you the D.O. CoC requires you to be collaborative, deflecting my questions asking what your concerns are to ask what steps I have done is non-collaborative behavior. I again ask you to enumerate your concerns.

The same holds true for you. You opened a task in this issue queue, and you are asking questions to a project maintainer. Using your words, I believe you should trust a a project maintainer for this queue, who has been a project moderator for years. Anyway, knowing which alternatives do exist just requires Drupal knowledge.

It was you arguing that we could not make certain changes

I have never said that the documentation in question is never changed. I do not see any reason for saying baring a written policy that can never be updated everything can be changed .

I am aware of at least on incident that involved myself making minor language changes to make the documentation match how project ownership queue admins (especially yourself @avpaderno) actual process requests.

You cannot make the documentation match how project moderators (that is the correct term) actually process requests, since you are not a project moderator.
Anyway, that was fixed, and it was not a relevant incident. It sounds also like creating an incident to then report those incidents should be avoided.

Addtionaly in ~2022 @avpaderno you deleted where these pages were originally stored, the Drupal Infrastructure team restored them and you again deleted them.

Truly, I replaced a documentation page with a documentation guide, and removed the existing documentation page to avoid confusion to people who would read the documentation in question. It was a change done when I was involved in an CWG issue, following what the CWG was telling me. That has been already explained to the DA.
Furthermore, that is a change I would have done even if I had to make commits in a drupal.org repository. It cannot be used as excuse to move documentation in a repository for which I am maintainer.

Essentially, there is no relevant incident which would justify moving documentation in the repository for this project.

Notice also that other documentation has been moved in drupal.org repositories because people responsible for that documentation decided to do so, handled by the people responsible for that documentation. It was not an initiative started from the outside.