Create the AsciiDoc Top-Level Project

Earlier today, the Eclipse Foundation's Board of Directors approved the creation of the AsciiDoc Top-Level Project. We'll use this issue to track all of the activities that we need to undertake to get bootstrap the new Top-Level Project.

Meta: creating Top-Level Projects is a relatively rare occurrence, so our processes are not particularly refined (combine this with the fact that we're evolving all of our processes). Given that the nature of when and how we stand up new Top-Level Projects is evolving, we need to also evolve corresponding process and tools. We'll use our experience with the creation of this Top-Level Project to capture the process as best we can and turn it into something more refined and repeatable. If anything is confusing at any point in this process, please ask for clarification. We will move quickly; your patience is appreciated.

To create a new Top-Level Project, the EMO needs to:

• Select a short name for the project
• Create a record in the Foundation DB (internal)
• Provision backend resources (e.g., LDAP)
• Assign the PMC Lead and PMC Member roles
• Create a record in the PMI
• Capture the charter in the PMI
• Create the PMC Mailing list
• Verify that PMC Lead and PMC Member roles have been propagated to the PMI
• Align existing subprojects with the new Top-Level Project
• Set up a call with the new PMC

Following our usual convention, the short name for the new Top-Level Project would be asciidoc, which would make the ID of the AsciiDoc Language project asciidoc.asciidoc meaning that the PMI page URL would, for example, become https://projects.eclipse.org/projects/asciidoc.asciidoc/. I have initiated a discussion with our infrastructure team to consider changing the way that we do project IDs, but that's a longer term issue. In the meantime, we need to fit in with our current infrastructure's requirements. I'll start a comment thread to discuss our options.

Aligning subprojects is primarily an organizational activity and mostly internal to the Eclipse Foundation. The ID, which reflects the project hierarchy, is used a few places so there will be some external changes. The PMI URL for the projects will, for example, change, but redirects will be set up in the process.

Subprojects that we need to align with the new Top-Level Project:

• technology.asciidoc
• technology.austen

My understanding is that there are no resource requirements for the new Top-Level Project. That is, there is no current need for Git repositories or a website. For completeness, the TLP is entitled to a website, but since the working group already has its own website, my assumption is that creating an additional website would just create confusion in the community. Please advise if my assumption is invalid.

The notion of committers on a Top-Level project is not generally meaningful in the case where a Top-Level project has none of its own resources. In the event that the Top-Level requires, say, a Git repository of it's own, we'll add committers.

Have I missed anything?

assigned to @webmaster

Following our usual convention, the short name for the new Top-Level Project would be asciidoc, which would make the ID of the AsciiDoc Language project asciidoc.asciidoc meaning that the PMI page URL would, for example, become https://projects.eclipse.org/projects/asciidoc.asciidoc/. I have initiated a discussion with our infrastructure team to consider changing the way that we do project IDs, but that's a longer term issue. In the meantime, we need to fit in with our current infrastructure's requirements.

Strictly speaking, we can just use asciidoc for both projects. It's a little weird, but only manifests in a handful of places. Or, we can select a different short name for the TLP, e.g., adoc.

Or, we can change the short name of the AsciiDoc Language project, e.g., asciidoc-lang (although this doesn't really address the weirdness of the redundancy) or maybe just lang.

If we follow my last suggestion, the two subprojects IDs would then become:

• asciidoc.lang
• asciidoc.austen

Note that these IDs are used mostly internally, but do manifest in some URLs (e.g., PMI as noted above) and in IPZilla (the audience for which is limited to committers).

Can you weigh in here @swhitesal and @mojavelinux?

added TLP label

@wbeaton Thank you for setting up this issue and listing out the steps in the process!

so our processes are not particularly refined (combine this with the fact that we're evolving all of our processes)

I'm clarifying (documenting for the first time in some cases) and evolving many of my day job's processes right now, so I empathize 100% with you. It's a lot of hard work

I'd prefer the short name for the AsciiDoc Language project to be asciidoc-lang and therefore the subproject ID would be asciidoc.asciidoc-lang. I agree, initially the redundancy seems awkward, but I've been bitten by not namespacing broad/high-level terms in the past (I've learned-the hard way -to namespace docs and community repos in a git organization). Also, by using asciidoc.asciidoc-lang, this mirrors the organizational structure and naming set up on gitlab.eclipse.org -> https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang.

In summary, I'd prefer the following subproject IDs:

• asciidoc.asciidoc-lang
• asciidoc.austen

However, if this causes conflicts with the current infrastructure requirements, let me know and we can revisit.

marked the checklist item Create a record in the Foundation DB (internal) as completed

marked the checklist item Assign the PMC Lead and PMC Member roles as completed

marked the checklist item Select a short name for the project as completed

Based on @swhitesal comment, I've proceeded to create the database record for the AsciiDoc project (shortname asciidoc) and I've added the PMC lead and members relationships in the DB. Shortly, we'll align existing subprojects with the new TLP, and with the new subproject ID specified by Sarah.

@webmaster please create the project mailing list.

marked the checklist item Create a record in the PMI as completed

marked the checklist item Capture the charter in the PMI as completed

marked the checklist item Create the PMC Mailing list as completed

marked the checklist item Verify that PMC Lead and PMC Member roles have been propagated to the PMI as completed

@swhitesal, @mojavelinux the PMI record for the AsciiDoc TLP has been created, as well as the project charter and the PMC mailing list.

I've also verified that PMC Lead and PMC Member roles have been propagated to the PMI correctly, and all looks good.

@webmaster please align the following subprojects to the AsciiDoc TLP, with the following subproject's IDs:

• Asciidoc Language: asciidoc.asciidoc-lang
• Eclipse Austen: asciidoc.austen

We've updated the foundation db and ldap so I think we're good here.

I've updated the PMI pages. I believe that we're good-to-go on the resources front.

Is the TLP going to get its own project and issue tracker?

We'll start making immediate use of it to discuss the creation of the logo.

I assume that when you say project you mean a Git repository.

@webmaster can you please create a Git repository for the AsciiDoc TLP?

Ok I've created: https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc for the TLP.

-M.

Thanks for creating the repository for the TLP.

However, now we have two parallel groups, AsciiDoc and AsciiDoc Language. The AsciiDoc Language group should not exist (https://gitlab.eclipse.org/eclipse/asciidoc-lang). Can you please remove it? The AsciiDoc Language is a project under the AsciiDoc group (https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang). Now there is a ghost project with the same name at https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang, which should not be there and is confusing people.

Ok I"ve queued https://gitlab.eclipse.org/eclipse/asciidoc-lang for deletion.

-M.

Thanks Maria Teresa.

Somehow, the AsciiDoc Language group got immediately recreated after it was deleted. Can we please get this right? I'm getting rather frustrated by this situation.

Also, can you make sure that all the right people have access to the AsciiDoc group? While I have maintainer access on the AsciiDoc Language group (that isn't even supposed to exist), I don't have maintainer access on the AsciiDoc group. And the AsciiDoc group has one member, whereas the AsciiDoc Language group has 14.

@mojavelinux we'll look into this and let you know when the situation is solved.

Any updates? Each day the duplicate asciidoc-lang repository exists, the more risk of confusion it causes.

I've spent some time this morning untangling what's happened here.

Our policy is that we create a single group under the the "eclipse" group for each project. The name for that group comes from what we refer to as the "short name" of the project which is the last segment in the id. So, the short name for the AsciiDoc TLP is "asciidoc" and for the AsciiDoc Language (asciidoc.asciidoc-lang), it's "asciidoc-lang". So our policy is that the repositories for the AsciiDoc TLP go in a GitLab group with the path "eclipse/asciidoc" and the AsciiDoc Language project's repositories go in a GitLab group with the path "eclipse/asciidoc-lang".

This is the current policy and our scripts are built to support that policy. We're having a discussion on Infra Issue 42 regarding changing this policy and script support.

So... when we moved the asciidoc-lang repository into the eclipse/asciidoc group, we basically moved that repository under the care of the AsciiDoc TLP. That was a mistake. A check is now in place to mitigate against us making that mistake again.

The correct location for the asciidoc-lang repository is, per current policy, eclipse/asciidoc-lang/asciidoc-lang. AFAICT the membership of that group is configured correctly.

@cguindon, please confirm that my assessment is correct.

@webmaster, to conform with our policy, we need to move the existing eclipse/asciidoc/asciidoc-lang repository to eclipse/asciidoc/asciidoc-lang/asciidoc-lang.

I've also noticed that the AsciiDoc TLP's repository (eclipse/asciidoc/asciidoc) isn't captured in the metadata. After we've untangled all of the above, let's please fix that as well.

The correct location for the asciidoc-lang repository is, per current policy, eclipse/asciidoc-lang/asciidoc-lang. AFAICT the membership of that group is configured correctly.

@cguindon, please confirm that my assessment is correct.

Affirmative.

We have some information on how this works in our sync script project: https://github.com/EclipseFdn/eclipsefdn-github-sync#gitlab-sync

Affirmative.

Thanks for the confirmation.

We need to get the AsciiDoc Language repository into a state where the project team can work.

@webmaster, can you please move the repository into the expected location?

Specifically,

• Delete the bogus empty repository: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang
• Move https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang to https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang/asciidoc-lang

Note that there are issues and MRs that need to be migrated along with the repository. Is there any risk that these will be broken when we move the repository? (this is my not-so-subtle way of asking that you confirm that these don't break with the move).

With that, I expect that the committers for the AsciiDoc Language project will have the necessary privileges to operate as committers on that repository.

Honestly I have no idea if the move will break issues(we haven't moved a live repo/project before), but based on https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#moving-issues since we're moving a project I would expect the issues to move 'automagically'

I've queued the deletion, so let me know if the above is confirmation enough. If it isn't I guess we'll need to test move and see what happens.

Whoa. Hold on. We cannot move the existing repository until the AsciiDoc WG SC is informed and can vote on this. This is a major change that impacts existing links. No where in my request did I ask for the existing repository to be moved. What we need right now is for the bogus asciidoc-lang/asciidoc-lang repository to be removed to prevent any further confusion.

@chrisguindon thinks that he might have a solution that makes the current configuration work. I'm going to get out of the way and let him see if he can sort it out. By way of expectation management, we're all out of the office until Tuesday.

marked the checklist item Align existing subprojects with the new Top-Level Project as completed

marked the checklist item Provision backend resources (e.g., LDAP) as completed

@wbeaton Can you please update the title of this issue so it reads "AsciiDoc" instead of "Asciidoc". This is a trademark issue.

Done.

FWIW, word marks are not case-sensitive.

Regardless, we'll do our best to be consistent (I took a quick look through our database and am pretty sure that we are consistently using "AsciiDoc")

Legally, it might be true that word marks are not case-sensitive. But this situation will be impossible to manage if we aren't ourselves consistent. I have been already fighting this battle for over a decade and each time we get it wrong, that error gets propagated 10x over. Enough of that and we'll never be able to correct it. So I'm asking the EF to be as careful as possible with this casing (and, it goes without saying, I will do the same).

changed title from Create the Asciidoc Top-Level Project to Create the AsciiDoc Top-Level Project

Good Afternoon,

I took some time today to review this issue to better understand the problem. I agree with @wbeaton that the priority is to get the AsciiDoc Language repository into a state where the project team can work.

I can see that the problem here started 2 weeks ago when the project requested that we move the AsciiDoc Language project under another project (AsciiDoc TLp): #65 (comment 138970)

Foundation staff needed to push back here but instead, we made an error and made the change without considering the consequences of such a move with our sync-script.

As mentioned by Wayne, we have a pre-defined strategy for creating groups and projects for the Eclipse Projects GitLab group. That structure is documented in our sync script: https://github.com/EclipseFdn/eclipsefdn-github-sync#gitlab-sync

We decided to apply this strategy to help our users to find our projects in a predictable format: https://gitlab.eclipse.org/eclipse/:eclipse_project/:repo_name

We also needed a solution that wouldn't require an excessive amount of API calls to keep things in sync since we need to run this sync script every 2 hours.

That's why we add committers to the Gitlab group and not the GitLab project (repository).

With that said, I do see some value in the nesting projects but at the same time, I currently see more value in keeping things consistent across projects for our users.

I am always open to making improvements to our processes. I think we should pursue the conversation regarding the pros and cons of changing our strategy but it's not something that we will change today: https://gitlab.eclipse.org/eclipsefdn/gitlab/-/issues/42

I do want to hear from other projects about this issue. There is a cost for us to implement a change to our sync strategy. We must make sure that this is something that other Eclipse projects needs or at the very least want.

If we want to get the AsciiDoc Language repository into a state where the project team can work, we must move https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang project back from the AsciiDoc TLP group to asciidoc-lang group https://gitlab.eclipse.org/eclipse/asciidoc-lang

I also recommend that we remove the AsciiDoc TLP from Gitlab since that project is not expected to provide code.

Please note that AsciiDoc TLP != AsciiDoc Working Group.

If the AsciiDoc WG is looking for an area to collaborate, we can create an AsciiDoc Working Group group under our Eclipse Working Groups group: https://gitlab.eclipse.org/eclipse-wg

We currently do not impose this structure for groups under the Eclipse Working Group group.

@mojavelinux I do understand there is a lot going on here. I am more than happy to jump on a call with you to discuss this if you want! Please let me know and I will set something up!

Thank you for the follow-up @cguindon. I now have a clear understanding of the constraints that were implemented and I understand that this is the system we have to work with.

The real root of the problem is that the asciidoc-lang project was never set up correctly according to the rules you laid out. It was created at the location asciidoc/asciidoc-lang and has always been there. That long predates the request to remove the duplicate asciidoc-lang/asciidoc-lang repository. (We never asked to move asciidoc-lang, but rather to remove the duplicate. Please study the history.) So we were off to a problematic start from the get go, and that's on the Eclipse Foundation. But that's behind us and I acknowledge that we need to focus on correcting the situation. And I'm willing to do that.

I accept the reality that the asciidoc-lang repository has to be moved to asciidoc-lang/asciidoc-lang. However, before we make that move, I have to inform the AsciiDoc WG of the situation at the next meeting (Sep 14). While I recognize that the AsciiDoc WG is not the AsciiDoc TLP, the WG members are the ones funding this whole initiative and it would be a slap in the face not to inform them and get their consent about a repository move / policy change at this stage. I will follow up once that action is ratified.

When the repository moves, it needs to be done without losing any existing data. To lose the work we've already done would be a major setback. So I'm asking for a guarantee that it can be moved safely. And please ensure that all the correct members and maintainers are attached to that repository.

I would also like to request that a redirect be set up from asciidoc/asciidoc-lang to asciidoc-lang/asciidoc-lang. We have a lot of inboound links to the asciidoc/asciidoc-lang repostiory already that we can't change and we don't want those to break. It's possible GitLab does that already when a repository is moved. In the event it does not, we are requesting that it be added manually.

As for the AsciiDoc TLP, I would like to request that the group and repository be named asciidoc-tlp (i.e., asciidoc-tlp/asciidoc-tlp). It will create massive confusion if the repository and group are named asciidoc (i.e., asciidoc/asciidoc). People will think that's the main repository for the spec and we will constantly have to be nursing that confusion. We don't want to go down that road. Since there's no overarching namespace for asciidoc (as I had originally hoped), we must qualify every group with a subject (e.g., asciidoc-lang, asciidoc-tlp, asciidoc-wg, etc)

I also recommend that we remove the AsciiDoc TLP from Gitlab since that project is not expected to provide code.

True, it does not provide code. But it will have documents and it will need an issue tracker. So the repository is still needed. We need a place to collaborate at that level.

Finally, yes, we would like to request a repository for the AsciiDoc WG. Based on the constraints you outlined, I accept the fact that the group and repository must be located under the eclipse-wg namespace. Please create the asciidoc-wg/asciidoc-wg repository under eclipse-wg. (At that time, I will move the existing issue in the AsciiDoc TLP to this repository).

I want to close by saying that I do appreciate your willingness to help. Please understand that my frustration predates your involvement. I have been expressing my frustration about a lack of communication on Eclipse's part in how projects get set up ever since the first issue was filed to create the asciidoc-lang repository. Mistakes have been made every step of the way. And those mistakes have set back the project's progress by months, if not longer. I'm trying to find patience in my well, but find myself scraping the bottom of the barrel.