Future of the asciidoc organization on GitHub

Skip to first unread message

Dan Allen

Aug 31, 2020, 9:45:57 PM8/31/20
to asci...@googlegroups.com
Fellow AsciiDoc community members,

The Asciidoctor project has been working with the maintainers of the AsciiDoc Python project (past and present), as well as the broader AsciiDoc community of users and integrators, to ensure the AsciiDoc language has a strong future. The first step was to set up an open and impartial industry working group to guide us towards this goal. I'm pleased to share that the AsciiDoc Working Group has been officially launched within the framework provided by the Eclipse Foundation (see https://www.eclipse.org/org/workinggroups/asciidoc-charter.php).

The objective of the Working Group is to govern the ongoing development of the AsciiDoc language (via the AsciiDoc Language project), provide a compatibility program for implementations (aka language processors), explore novel uses of the language, and collaborate on initiatives to promote the language and ecosystem. This approach not only prevents flavors of AsciiDoc from emerging, the community from splintering, or the language stagnating, it also takes the burden off of implementations to define, document, and promote the language. In other words, it gets us all on the same page and working together. To learn more what this effort is all about, see https://www.eclipse.org/org/workinggroups/explore.php.

The AsciiDoc Language project has also been created (see https://projects.eclipse.org/projects/technology.asciidoc), though it's still going through the legal process to accept the initial contribution (in the form of the user-oriented reference documentation). We're steadily moving ahead, though there are plenty of matters still to address.

That brings us to the matter of this email. The current owners of the asciidoc organization on GitHub (Stuart, Lex, Michel, and myself) have been in communication about repurposing the organization to host the language specification, TCK, and asciidoc-lang.org website, one or more implementations, the asciidoc.org website, and other keystone projects under the governance of the AsciiDoc Working Group and/or AsciiDoc top-level project at the Eclipse Foundation.

Making this transition means there will be changes to the asciidoc organization on GitHub. If we decide to move forward with this plan, the Eclipse Foundation will become an owner on the asciidoc organization (once it's cleared out, see below). Adding new projects to the organization will at least require approval from the AsciiDoc Working Group (by following the Eclipse processes) and ideally be Eclipse projects themselves [1]. An alternate approach would be to create a new organization (e.g., asciidoc-spec) for Eclipse projects and use the existing asciidoc organization for new, non-Eclipse projects. We're still sorting out our options and negotiating them with the Eclipse Foundation. More to come. Either way, there will be a place for both Eclipse and non-Eclipse projects alike to live.

That raises the matter of the existing repositories. These repositories will move to their own organization, most notably the asciidoc-py3 project to asciidoc-py. We've yet to determine what will happen with the legacy asciidoc/asciidoc repository, though we'll be mindful of existing references and handle them accordingly. We may be able to archive the repository and keep it where it is for a fixed period of time, then later move it to another organization on GitHub such as asciidoc-py.

There's also the matter of the asciidoc.org website. The plan is to make it the point of entry for the AsciiDoc ecosystem (as we've always envisioned). It would present a brief introduction to AsciiDoc and the Working Group, provide a quickstart guide and/or cheat sheet for the language, and offer an inclusive, impartial directory of implementations, tools, and other resources in the ecosystem. (The Working Group will budget us the necessary resources for this initiative). A new website, asciidoc-lang.org, will host the spec document and user-oriented language guide (since that part will be managed by the AsciiDoc Language project).

That leads us to the question about what to do with the existing website content on asciidoc.org. The existing content will remain where it is for now and we'll aim to change it somewhere in the Q1 2021 timeframe. At that time, the existing content would need to be moved to another site, such as asciidoc-py.org (if it hasn't already by then). We'll redirect existing links to that location, where appropriate. Until that time, we'll add a notice at the top of the current website so visitors are aware of this upcoming change and can plan for it (Matthew and Lex, let's coordinate to make this update).

To stay informed about what's happening with the AsciiDoc Working Group and its activities, I encourage you to subscribe to the asciidoc-wg list (https://accounts.eclipse.org/mailing-list/asciidoc-wg). To follow or participate in the development of the AsciiDoc language specification, I encourage you to subscribe to the aciidoc-lang-dev list (https://accounts.eclipse.org/mailing-list/asciidoc-lang-dev). To contribute code, you'll need to sign the Eclipse Contributor Agreement. This is merely an assertion that the code you're contributing is code you wrote and you have the necessary rights to contribute it. That ultimately protects the software so that it continues to be free to use by all. (See https://www.eclipse.org/legal/ecafaq.php).

I welcome your feedback on this message and how best to handle this transition.

Best Regards,


p.s. I also want to add that if anyone has difficulty participating in the AsciiDoc Working Group or AsciiDoc Language Project, please bring it to my attention immediately. By undergoing this effort, we're striving for complete openness, transparency, and access. I'll accept nothing less.

[1] AsciiDoc-related projects can still be created anywhere else without permission, though they are subject to the trademark guidelines regarding the use of the name AsciiDoc (see https://www.eclipse.org/lists/incubation/msg00723.html).

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux
Reply all
Reply to author
0 new messages