Current draft: https://www.mediawiki.org/wiki/User:Loren_Johnson_(WMDE)/drafts

I think this should wait for https://phabricator.wikimedia.org/T340234, but it doesn't need to. The idea being that even if we still update this before doing anything new with our distribution story, the output of that spike should give us better information about where the documentation is heading and we can make an intermediate edit better with that awareness.

@danshick-wmde / @darthmon_wmde : Hi, the Due Date set for this open task passed a while ago.
Could you please either update or reset the Due Date (by clicking Edit Task), or set the status of this task to resolved in case this task is done? Thanks!

Hi there, is it time for me to act on this task? If so, who shall I approach as my subject-matter expert?

As decided via T365427, this will be handled by putting a link to github on the install page as soon as T362226 is merged.

I changed these 2:

• https://www.mediawiki.org/wiki/Wikibase/Docker
• https://www.mediawiki.org/wiki/Wikibase/Suite

Now they both look like this:

however, I went to:

• "what links here" from Wikibase/Docker
• "what links here" from Wikibase/Suite

and found that we need to do some more cleaning up there. I will close this ticket since this part is done and will open a new one that needs more curation from @danshick-wmde and @jon_amar-WMDE :)

@lojo_wmde wrote on https://github.com/wmde/wikibase-release-pipeline/pull/730

Worth noting is that currently https://www.mediawiki.org/wiki/Wikibase/Docker links to the main branch and the deploy directory https://github.com/wmde/wikibase-release-pipeline/tree/main/deploy, but I was expecting it to link to the README.md at the tag of the most recent release, i.e. https://github.com/wmde/wikibase-release-pipeline/blob/v3.0.0/deploy/README.md

Now that I'm back at work I've updated the page to link straight to the GitHub docs. I removed the old instructions but left the FAQ for now.

Worth noting is that currently https://www.mediawiki.org/wiki/Wikibase/Docker links to the main branch and the deploy directory https://github.com/wmde/wikibase-release-pipeline/tree/main/deploy, but I was expecting it to link to the README.md at the tag of the most recent release, i.e. https://github.com/wmde/wikibase-release-pipeline/blob/v3.0.0/deploy/README.md

That would entail updating the link on the wiki every time there's a release. The idea is that we only need to update documents in one place when changes occur. Visitors to https://github.com/wmde/wikibase-release-pipeline/tree/main/deploy will see the latest version by default, unless I miss my guess?

I see the thinking behind linking to the tagged version. However, (1) after every release we merge the release branch into main so that main will have the very last version even after the release, (2) we are aiming to not only improve our documentation but also reduce the maintenance costs whilst keeping it up to date. Linking to the tagged version would go against the last part of that goal, since we would need to add a somewhat unnecessary* step into the release process.

(*) unnecessary coming from the fact that the last version would also be found in the main branch apart from the tagged branch

The main branch is our "development" branch. The documentation on main could contain references to unreleased functionality, which is not intended for production use yet. That's why I also support the idea to link to deploy-3, even though we would need to update that as soon as we have a new major release.

We could consider having a latest-stable branch to link to. This would involve some restructuring of the repo though. The current work on the mono repo structure could offer some options here in the future.

Right, I see what you are saying. Thanks for the specifics. However, we are talking about the code and the install documentation and the documentation of the Release Pipeline. From what I have understood from Jon we are getting into more user facing features in the next months and won't be changing the pipeline code much, hence, the documentation either.

Now my pragmatic question would be for @jon_amar-WMDE and @danshick-wmde: what would you rather do? as I see it there are the following options:

1. we leave it as it is for now. This means that, as Robert mentioned, people following the link will get to the very last state of our pipeline, which may not be the very last version we have released. Otoh we may not make very substantial changes in the pipeline code before the next release.
2. we change the documentation now to the deploy-3, which is the latest version that has been released. We need to make sure that we change it again after next release.

In any case I see value in creating a "latest-stable" tag of sorts to point to so that we spare that maintenance and we will be able to soon (enough) create a "latest-stable" tag, as Robert mentioned. We would change it in the documentation so that we won't have the issue that it gets outdated with every release.

• I like for now linking to the latest release, and I am also equally ok just linking to the main branch from the Wiki page and updating that with each release of Deploy.
• Soon, without a huge effort, we can automate the updating of that page from our release scripts to put whatever we want there verbatim along with a release (via Action API... lala).
• Currently what we do on the DockerHub homepage is possibly a model for now / going forward. There we list all the currently supported versions and link to the related documentation. Again, this is a page both in our repo and on the Wiki which we can generate from a template as part of our automated releases...

A bit of commentary in this general direction:

Given the devops / engineering centric core audience which I still see as our audience for now (due to the current state and nature of our project), I think we should be leaning fully into the conventions of README.md, CHANGELOG.md, MIGRATION.md, Github Releases, etc. As we fill-in and make coherent each of those for each of the products, from the root directory which is an index, up to deploy and the same files in each build/<image-name> directory, I think it will be taking us and our users in the right direction. From there we can build on top of that softer entry documentation for non-dev / non-devops as we also find ways to move more in that direction in the product/s itself... Hope that makes sense or is of some value to state.

thanks a lot for your input, @roti_WMDE , @lojo_wmde !

@jon_amar-WMDE your decision is required here :)

Hi all,

OK, I get it now -- I didn't realize the main branch was the equivalent of a dev branch. I would like to uphold the principle of "update docs in exactly one place", so if I had my druthers I would like there to be a latest-stable branch. However, if we can update various sources programmatically (with tests that verify the updates), that works for me too, of course. I support whatever the development team thinks is best, as long as we're not making multiple updates subject to human fallibility.

generally landing in the same place as @danschick-wmde, i.e. reliable links without manual intervention, either programatically or to a latest-stable branch. my preference would be to a latest stable tho as then we could share this link in more places knowing it will continue to be reliable (ex. in an email, on wikiba.se, in telegram headers, etc). that said I'm fine with a manual solution for the interim while we lay the foundation for the above. ideally we'd get there before too long tho. let's discuss the implementation details if there's some nuance there.

I would love tho to better understand what the typical conventions are in this space, to @lojo_wmde 's pont:

we should be leaning fully into the conventions of README.md, CHANGELOG.md, MIGRATION.md, Github Releases, etc. As we fill-in and make coherent each of those

what are these conventions in this particular context?

They don't have a name per se, but are something like Open Source project conventions: https://stackoverflow.com/questions/37428057/what-are-special-files-like-changelog-license-version-contributing-new-issue-cal