Retrospective: Moving AsciiDoc to the Eclipse Foundation
This is the first pass. This is the history and current state as I understand it. Corrections welcome.
My intention with writing this is to document the failures so that we can take corrective steps to reduce the risk of repeat.
Summary
We made a number of errors while moving AsciiDoc over to the Eclipse Foundation. Fundamentally, we failed to take the full scope of the effort into consideration and decisions that were made early in the process worked us into unanticipated corners later in the process.
History
The first project that we created was for the AsciiDoc Language specification with the short name asciidoc
. We provisioned resources based on this short name. Specifically, we created a mailing list named asciidoc-dev@eclipse.org
but later (driven by the project team) changed it to asciidoc-lang-dev@eclipse.org
. We also initially provisioned a repository on GitHub, https://github.com/eclipse/asciidoc
.
This was our first mistake. The project should have been created with the short name asciidoc-lang
. Compounding that error, we followed our usual script (the same script that we've been following for years) and did the "usual sorts of things". Starting with an incorrect short name, the "usual sorts of things" resulted in us creating all of the wrong things. This was all amplified by our transition to GitLab, and the EMO's general lack of familiarity with it and the implications of its adoption on our processes. The root of the problem, however, is that we did not communicate what we were doing with the project team, resulting in confusion and a lot of unnecessary churn to get back on track.
To mitigate against this in the future, our standard practice has been updated to ensure that the project team is informed early (and has an opportunity to influence) in the specific resources that we will provision for them.
The significance of the choice of short name wasn't immediately understood by the entire team. The larger "we" knew that a top level project was coming, but failed to make the connection that the top level project would take over the asciidoc
short name and that we'd have to change the existing subproject's short name to asciidoc-lang
. Had we initially provisioned AsciiDoc Language as asciidoc-lang
and provisioned all resources accordingly, this would be the end of the retrospective...
By way of background, the "short name" is, basically, the technical name. It's used in technical namespaces like, URLs for project websites (e.g., the Eclipse Dash project with short name dash
has a website at https://www.eclipse.org/dash). At least in theory it's also used in code namespaces, (e.g., the Java packages in the Eclipse Dash project take the form org.eclipse.dash.*
). The short name is also part of the complete project id, which is the short name pre-pended with the id of the parent project. AsciiDoc Language started as technology.asciidoc
, but then became asciidoc.asciidoc-lang
when we created the top level project. An implication of our use of it in technical namespaces is that the short name must be unique across our project space.
Because the short name is used in technical namespaces, we tend to try and keep it as short as possible. This, again, is part of our usual script.
To mitigate against this in the future, we need to take care to ensure that the short name that we select (and the implications of that selection) is communicated to the project team and that we take care to ensure that we're taking the full picture into consideration.
The way that we have GitLab set up is that the short name is a critical part of the repository path. When we initially provisioned the original AsciiDoc Language project (technology.asciidoc
), we created a repository for the project team on GitLab using the pattern "eclipse/<shortname>/<repository>". That is, we created a repository with eclipse/asciidoc/asciidoc-lang
as the path.
By way of background, the systems that manage our GitLab repositories assume that the repositories for a project are all collected under a single group that uses the project's short name. That is, all repositories for the asciidoc.asciidoc-lang
project are assumed to exist under eclipse/asciidoc-lang/*
in our GitLab instance.
When we later created a new AsciiDoc top level project, we decided that the top level project's short name should be asciidoc
, and that the realigned AsciiDoc Language project should be asciidoc.asciidoc-lang
(i.e., the short name would need to be changed to asciidoc-lang
). Making this change effectively orphaned the existing eclipse/asciidoc/asciidoc-lang
repository.
We failed to notice this.
To mitigate against this in the future, we should put checks in place to identify this error state and process to correct it. It is also the case that the GitLab group/short name alignment may be too restrictive (see infrastructure issue 42).
Our failure to notice and comprehend the error left us in a state of doing nothing. The worst part of this is that the EMO was waiting for the project team to do something, while they were in a state where they could literally do nothing.
The solution that we have at the moment is to move the eclipse/asciidoc/asciidoc-lang
repository to eclipse/asciidoc-lang/asciidoc-lang
. This is suboptimal as it requires that the project team and AsciiDoc working group update the links that they've published to the repository and point their community to the new location.
Note that at the PMC's request, we've also created an repository for the AsciiDoc top level project, eclipse/asciidoc/asciidoc
. Top level projects having resources is not common, but not wrong. Our only notion of a team with access to a repository is a team of committers and the notion of committer on a top level project is weird. Our practice is to just grant PMC members committer status, but this doesn't happen automatically. Since PMC members don't necessarily need write access to TLP resources, we often don't discover that a PMC doesn't have committer status on TLP resources until some significant amount of time there after. As a matter of practice, the EMO will automatically grant committer status on TLP resources to a PMC member who asks.
What Now?
What do we learn from this experience?
We need to communicate more across Eclipse Foundation and project teams as we bring projects onboard so that we have at least a fighting chance of identifying the pitfalls early in the process.
We need to focus more attention on identifying and breaking logjams. Leaving project teams in a holding pattern is unacceptable.
We need to better document our practices and take steps to ensure that folks bringing projects to the Eclipse Foundation better understand what they're getting into.
This all happened while we were transitioning from Bugzilla to GitLab. We tweaked our processes in the the process and I believe that we are now in a position to provide generally better service (i.e., we've addressed some of the mitigation items described above). While engaging in this change might have distracted us a bit, I don't believe that it necessarily played a factor the mistakes made.
I fear that the most important take-away is that we got lost in our own complexity. Things that ultimately were minor errors threw us into a state where we literally gridlocked. Reducing complexity has to be a goal as we move forward.
/cc @pbuckd40 @mdelgado624 @cguindon @mojavelinux @swhitesal @mward @droy