Infrastructure Migration

[elextr]

As suggested by @mojavelinux on asiidoc-py3 this issue is to discuss the migration of infrastructure around the Asciidoc Python2, asciidoc-py3 repositories as asciidoc-py2 transitions to EOL:

1. asciidoc python 2 repository name (if its EOL it shouldn't have the canonical asciidoc/asciidoc repo, thats been suggested as a location for overall Asciidoc language discussion independent of the various implementations)

2. how to manage documentation for both asciidoc-py2 and -py3 being visible at the same time.

3. how to maintain a released and a development copy of the docs.

[aerostitch]

While I agree that we should have a distinction between the asciidoc language and the asciidoc tooling, I'm wondering if it's really worth keeping documentations for both asciidoc-p2 and asciidoc-py3.

The python2 version is unlikely to see any code change in the future (and maybe the repo should be archived, aka put as read-only) to make sure of that.

All the commits that are in the python 2 version are now in the python3 version so we could probably consider the python3 version as the continuation of the python2 version (just as if we had done that in a new branch of the same repo maybe?).

All the distros are dropping python2 right now, so maybe let's just say that this repo is done and go on with they python3 repo now.

[elextr]

wondering if it's really worth keeping documentations for both asciidoc-p2 and asciidoc-py3.

Yes past EOL of the Python 2 version I agree that the docs don't need to be visible, its just in the interim.

(and maybe the repo should be archived, aka put as read-only)

Yes after EOL and rename.

All the distros are dropping python2 right now, so maybe let's just say that this repo is done and go on with they python3 repo now.

Current distros may be, but long term support versions (eg Centos and other Redhat versions, even Ubuntu LTS) are not. And projects still have to move, Git for example is still capable of building with either asciidoc or asciidoctor, does it work with asciidoc-py3?

[aerostitch]

Are you planning to rename asciidoc/asciidoc-py3 to asciidoc/asciidoc once you're done or just keep asciidoc/asciidoc for the language specs documentation? (That would change a bit the way I'll handle the migration in Debian. If the py3 repo is renamed to asciidoc. I don't need to create a new package, I just need to do a version upgrade, which changes a lot of things because this way the packages depending on it don't need to change their dependencies...)

[elextr]

I don't think that any implementation is a "reference implementation" any more. So no implementation should be occupying that namespace.

Thats why the idea of the Asciidoc standard work there , multiple implementations are a good thing, it avoids things like the Python2 EOL being an ending and it supports more use-cases (such as Asciidoctor Ruby for use on Github) but its important to agree commonalities, we don't want to end up with the Markdown effect.

Now installing an implementation as asciidoc is also an interesting question. Maybe you distro guys can handle it with NSS? But thats not a solution for Windows and OSX AFAIK.

[mojavelinux]

I have a lot to say here, but I want to jump on something specific before I get into the bigger picture. I want to address the repository name.

For various reasons, it's not a good idea to put something different into the space of an existing repository. But it is reasonable to rename a repository (as long as it redirects a visitor / tool to the right location, which GitHub handles).

What I think should happen is that asciidoc/asciidoc should be renamed / redirect to asciidoc/asciidoc-py2. Anyone who tries to clone the old URL will still get the same code. (We could also consider having it redirect to asciidoc/asciidoc-py3, but we'd have to ask GitHub to set that up since it won't get set up automatically). In this scenario, asciidoc/asciidoc will only exist as a redirect.

The asciidoc.org website would then get split off as asciidoc/asciidoc.org.

If we do it this way, we won't cause any surprises.

[mojavelinux]

Actually, if we rename in this order, the redirect should get set up automatically:

1. Rename asciidoc/asciidoc to asciidoc/asciidoc-py2
2. Rename asciidoc/asciidoc-py3 to asciidoc/asciidoc
3. Rename asciidoc/asciidoc to asciidoc/asciidoc-py3

I can't guarantee it, but I think that will set up the redirects without having to ask GitHub. If for some reason it doesn't, we can always ask them to fix it.

[elextr]

I have some concerns with this:

1. I agree with this renaming and AFAIK github will redirect existing references to the new repository

2. and 3. I am not so sure about because it perpetuates the link between Asciidoc repository and a particular implementation. Its better that it is a Python3 implementation, but I believe its better to break the linkage to implementations, instead it should have content that explains the implementations and of course has manual links to the implementations so users can choose the appropriate one. Otherwise the documentation for that implementation becomes associated with the canonical Asciidoc namespace, but asciidoc-py3 is not the same as Asciidoctor or other implementations.

Using that namespace for a standardisation and modernisation effort may indeed not be the right thing, but to me asciidoc.org sounds like a website, not the language standardisation effort.

[mojavelinux]

I am not so sure about because it perpetuates the link between Asciidoc repository and a particular implementation. Its better that it is a Python3 implementation

Actually, I don't think it does. Sure, it redirects from asciidoc/asciidoc to asciidoc/asciidoc-py3, but that makes it clear that people should start referring to it that way. Since there is no generic AsciiDoc software, the namespace of asciidoc/asciidoc should redirect, at least until everyone has a chance to stop referencing it. asciidoc/asciidoc.org (or even asciidoc/spec.asciidoc.org) would then serve has the front page for AsciiDoc the language...and it's clear it is not software, but rather information.

Maybe in a year we could reoccupy asciidoc/asciidoc with something else, but it would be a disaster to do that without a healthy transition period.

[elextr]

would then serve has the front page for AsciiDoc the language...and it's clear it is not software, but rather information.

Agree, we both have the same end in sight.

Maybe in a year we could reoccupy asciidoc/asciidoc with something else, but it would be a disaster to do that without a healthy transition period.

Ok, I havn't tried accessing a renamed repository via a redirect, does Github simply use the redirect to find the new name and then behaves as if the user started at the new name?

If thats the case then users are likely to notice the name change, just needs to be clearly noted on the landing page for the new repository that they should use the new name (with redirect drop dead date).

After we bring up the new language pages it can still have a note as the first thing that the asciidoc-py2/3 is now under those names so users who havn't caught up can still find where to redirect to.

By the way isn't redirecting asciidoc/asciidoc to asciidoc/asciidoc-py3 going to break all the Github forks and user clones that were cloned from what is now asciidoc/asciidoc-py2 but still point to asciidoc/asciidoc? Won't they suddenly find all the upstream Python 3 changes pending?

[MasterOdin]

does Github simply use the redirect to find the new name and then behaves as if the user started at the new name?

That's correct. Any requests for the code (git pull, push, etc) as well as some number of web requests (ie. issues, pull requests, etc) will redirect to the new URL.

See: https://help.github.com/articles/renaming-a-repository/

[mojavelinux]

Ok, I havn't tried accessing a renamed repository via a redirect, does Github simply use the redirect to find the new name and then behaves as if the user started at the new name?

If you create a new repository where there is an existing redirect, GitHub silently removes the redirect and allows the repository to occupy that space.

[mojavelinux]

By the way isn't redirecting asciidoc/asciidoc to asciidoc/asciidoc-py3 going to break all the Github forks and user clones that were cloned from what is now asciidoc/asciidoc-py2 but still point to asciidoc/asciidoc? Won't they suddenly find all the upstream Python 3 changes pending?

It is true that the code would jump way forwards. But since it's still a full history, they can then jump backwards to previous tags.

But we should still consider whether defaulting to py2 or py3 is the right move.

My concern with changing the contents isn't so much about making it static. It's just that there are a lot of references out there to that source repository (such as in RPM and DEB packages) and people expect to find the source there. It's not nice to put something different there. I think that erodes trust. It's okay to redirect because tools will follow the redirect. But if you just swap it with something different, then no redirect happens and it's not clear where the code went. (At least give it a year, then maybe that would be okay to do by then).

[MasterOdin]

Done