Plone 6 Docs Final Release Checklist

[stevepiercy]

Plone 6 Docs Plan

This is a checklist of tasks to perform just before the launch of the final release of Plone 6 Docs. Please add items as needed.

We will add latest.docs.plone.org as an alias for 6.docs.plone.org. This could possibly future proof docs to always point at the latest URL as the version of Plone increases. It could also detect when a page moves with linkcheck and intersphinx.

Plone 6 Docs Questions

• How do we handle 404s to docs.plone.org? See comments starting with Plone 6 Docs Final Release Checklist #1140 (comment)

Plone 5 and earlier Docs

• Create Plone 5 docs at 5.docs.plone.org
• Create Plone 4 docs at 4.docs.plone.org
• Create Plone 3 docs at 3.docs.plone.org
• Update Plone 5 theme to have a banner across the top, similar to https://docs.python.org/3.5/. Alternatively update Plone 5 version switcher to include Plone 6.
• Consider updating the 3 and 4 version switchers to include 6, if possible.
• Search results (Algolia) of 5.docs.plone.org should point to 5.docs.plone.org not docs.plone.org #1375 Figure out where and by who the Algolia search is configured, change configuration and/or create new configuration

Plone 6 Docs to do now items

• Redirect api.plone.org to 6.docs.plone.org/plone.api. See Redirect api.plone.org to Plone 6 Documentation #1383
• Create a version switcher on Plone 6 docs for previous versions. #1381
• Label should read "Plone 6 Documentation" or similar without "dev" #1382
• Ensure Matomo Analytics tracks 6.docs.plone.org.
• Create an alias of latest.docs.plone.org to point to 6.docs.plone.org.
• Update base URL of sitemap and other URLs in conf.py. Links and sitemap and more after v6 release #1385
• Update base URL of sitemap and other URLs in conf.py. Fix ogp_image URL plone.restapi#1556
• Update base URL of sitemap and other URLs in conf.py. Fix URLs to Plone 6 docs volto#4143
• Check robots.txt.
• Update Netlify to build previews on the 6.0 branch as well as 6-dev. We will continue to use 6-dev for development and testing.

Prepare each submodule for testing

• In each conf.py, update the Intersphinx plone target to 6.docs.plone.org.
• In plone/plone.api, update the URLs containing 6.dev-docs.plone.org to 6.docs.plone.org.
• In plone/plone.restapi, update the URLs containing 6.dev-docs.plone.org to 6.docs.plone.org.
• In plone/volto, update the URLs containing 6.dev-docs.plone.org to 6.docs.plone.org. Use new URL 6.docs.plone.org volto#4726

Canceled

• Change Volto's submodule branch to be pulled into plone/documentation from master to 16.x.x (latest and stable). EDIT: Not feasible. See Plone 6 Docs Final Release Checklist #1140 (comment)
• In each submodule, create a new branch, 6-deploy, to be merged into the latest and stable branch of each repo. See Plone 6 Docs Final Release Checklist #1140 (comment)
• Update plone/documentation Makefile to pull in these submodules' new branches for testing. See Plone 6 Docs Final Release Checklist #1140 (comment)
• Merge each submodules' 6-deploy branch into its stable and latest branch, either master or 16.x.x for Volto. See Plone 6 Docs Final Release Checklist #1140 (comment)
• Update plone/documentation Makefile to pull in these submodules' master or 16.x.x branch for deployment. See Plone 6 Docs Final Release Checklist #1140 (comment)

Must be done before launch

• Update redirect for https://docs.voltocms.com/ to https://6.docs.plone.org/volto on https://6.docs.plone.org/volto/ volto#4148 @polyester @fredvd @ericof
• Redirect 6.dev-docs.plone.org to 6.docs.plone.org. Run linkcheckbroken from Training, Documentation and its submodules. Purge that old version from the server. Google has indexed that site, leading to very confusing and outdated search results. @polyester
• Remove alias 6.dev-docs.plone.org. @polyester
• Create an automatic deployment of 6.0 branch to 6.docs.plone.org (update server paths?). @polyester
• In conf.py under linkcheck_ignore, clean up any remaining commented links. @stevepiercy
• Merge 6-dev into 6.0. @stevepiercy
• Automatically deploy 6.docs.plone.org. @stevepiercy
• Set 6.0 as default branch. @stevepiercy
• Redirect docs.plone.org to 6.docs.plone.org. @polyester
• Update Matomo configuration to track docs.plone.org under "Plone 6 Docs" instead of "Plone 3-4-5 Docs". See https://stats.plone.org/index.php?date=yesterday&module=SitesManager&format=html&action=index&idSite=2&period=day&segment=&widget=&showtitle=1&random=1154#?period=day&date=yesterday @stevepiercy
• Run linkcheckbroken on Training and REST API. @stevepiercy
• Add custom 404 not found page #1400 and configure server to use /404.html as the error page. @polyester
• Announce to Community Forum, social media, etc., of the changes. @stevepiercy

[MrTango]

I really think a version number in the url or path makes sense.
We could already activate it and could use the url in places like field description or tempaltes to point into the documentation.
So somthing like 6.docs.plone.org would be awesome and docs.plone.org could be a redicred on it as long as Plone 6 is the newses. But 6.docs.plone.org will continue to work even when Plone 7 is out.

[stevepiercy]

I think that RTD was on to something with the concept of latest as a synonym for the latest stable version number. IOW, when we release v6 of docs, latest would be aliased to 6:

https://6.docs.plone.org/foo
https://latest.docs.plone.org/foo

When 7 comes out, then latest would be aliased to 7. This way you can always have links to latest that never need to change (unless the path changes, of course), or to previous versions for archival reference.

[polyester]

Given the inflexibility of the 5 and pre-5 versioning system, and the fact that two different physical servers are involved, it would be much easier to have DNS-based diffence. So 5.docs.plone.org instead of docs.plone.org/5.

In that case docs.plone.org, latest.docs.plone.org and 6.docs.plone.org will soon all point to the version6 documentation, whereas 5.docs.plone.org, 4.docs.plone.org and 3.docs.plone.org point to the old ones. That way, the version-switcher on the old docs is easily adaptable, and even 3.docs.plone.org will have a direct dropdown to 6

If that's OK, I can start creating the necessary stuff for the [5-3] versions. It will incur of course a one-time searchengines confusion, but we'd have that anyway.

Opinions, strong objections?

[stevepiercy]

In that case docs.plone.org, latest.docs.plone.org and 6.docs.plone.org will soon all point to the version6 documentation, whereas 5.docs.plone.org, 4.docs.plone.org and 3.docs.plone.org point to the old ones. That way, the version-switcher on the old docs is easily adaptable, and even 3.docs.plone.org will have a direct dropdown to 6

@polyester thanks for the feedback. I support this plan, with a few changes in both your suggestions and my original checklist.

• docs.plone.org/.* redirect to either 6.docs.plone.org/.* or latest.docs.plone.org/.*. The reason for this is to deter the bookmarking of and linking to docs.plone.org and instead use either a version number or latest. Henceforth any links to docs.plone.org would clearly be for Plone 5.2 and earlier.

• As far as to which subdomain to target for redirecting from docs.plone.org, I have changed my mind. I prefer an explicit version number, 6 for now, as the target instead of latest. Reason being that then any future bookmarks and links shall always be bound to a specific version of Plone documentation and shall never rot. Authors will copy and paste those URLs going forward. It clearly tells the reader of Training and other documentation what version their writings target. There shall always be the option to use latest, if the author so chooses, but it would be a conscious and deliberate decision.

• Set up a 404 page containing links to potential pages for each version of Plone. For example:

  404 - Not found

  Perhaps you seek a page for a specific version of Plone documentation?

  • https://6.docs.plone.org/quickstart/index.html
  • https://5.docs.plone.org/quickstart/index.html
  • https://4.docs.plone.org/quickstart/index.html
  • https://3.docs.plone.org/quickstart/index.html

• Upon final agreement, I update the checklist at the top of this issue with our decisions.

Please provide opinions and feedback. Thank you!

[polyester]

In general, agreement. On the 404 page, given the quite extensive changes to URLs, I would probably be in favor of not offering https://x.docs.plone.org/whateveryouwerelookingfor, which is likely to not exist, but just an overview of https://x.docs.plone.org versions.

As the de-facto "Keeper of the Ancient Scrolls", we already have an insane amount of NGINX redirects, and maintaining that in the future is a recipe for failure. Pointing the user to the entry point is probably wiser.

[stevepiercy]

Are these just static content servers that have nothing dynamic? If so, that makes sense.

But if nginx can grab the filepath, pass it to a template, which in turn can render the filepath, it would be useful to the user and not require any additional redirect maintenance. Did I explain that well?

IOW, a typical flow:

1. Visit https://docs.plone.org/(.*)$.

2. Redirect to https://6.docs.plone.org/(.*)$ [edited to include 6] which, if it does not exist, contains the message:

   404 - Not found
   
   Perhaps you seek a page for a specific version of Plone documentation?
   
   https://6.docs.plone.org/\1
   https://5.docs.plone.org/\1
   https://4.docs.plone.org/\1
   https://3.docs.plone.org/\1
   

   We might also be able to use the nginx $request_uri.

[polyester]

Plone [5-3] are just static HTML sites, but it has been a challenge to map things. There's simply no way you can map https://6.docs.plone.org/some-fancy-newtech to https://3.docs.plone.org/when-dinosaurs-still-roamed-the-earth

I can probably whip up some "if not found, redirect to the canonical https://3.docs.plone.org" NGINX magic, but it might be challenging. I'll try.

[stevepiercy]

Ack, I goofed by omitting the target to redirect to 6. I edited my previous comment to reflect what I want. Please take another look, and let me know. I hope that makes sense now.

[polyester]

as preparation, the following are now live:

• https://3.docs.plone.org
• https://4.docs.plone.org
• https://5.docs.plone.org

[stevepiercy]

I have updated the checklist at the top to reflect the completed tasks and our desire to use #.docs.plone.org as URLs for each version.

[polyester]

@stevepiercy For 6.docs.plone.org: that currently (and actually since february already, just nobody noticed...) that is set up as an NGINX "alias" to 6.dev-docs.plone.org - so links to 6.docs.plone.org already work.

Would be nicer to make it official, so that the name and filepath (currently /var/www/6.dev-docs.plone.org) reflect the official status, but there is no time pressure, just a need to coordinate because an ansible role needs to run to do the NGINX changes, and a github actions change plus deploy to deploy.

Not sure if it's wiser to keep 6.dev-docs.plone.org as an alias for 6.docs.plone.org for a while, or just do a redirect.

[stevepiercy]

Would be nicer to make it official, so that the name and filepath (currently /var/www/6.dev-docs.plone.org) reflect the official status, but there is no time pressure, just a need to coordinate because an ansible role needs to run to do the NGINX changes, and a github actions change plus deploy to deploy.

I have no access to make any of those changes.

Not sure if it's wiser to keep 6.dev-docs.plone.org as an alias for 6.docs.plone.org for a while, or just do a redirect.

Redirects will cause builds to fail wherever linkcheck is run against 6.dev-docs.plone.org. This should be announced and scheduled far in advance to give all the submodules' docs and trainings authors to update their material. I think we should do this task last. I've added it to the checklist.

[polyester]

I have no access to make any of those changes.

I do, after some soul- and passwordmanager-searching.

Not sure if it's wiser to keep 6.dev-docs.plone.org as an alias for 6.docs.plone.org for a while, or just do a redirect.

Redirects will cause builds to fail wherever linkcheck is run against 6.dev-docs.plone.org. This should be announced and scheduled far in advance to give all the submodules' docs and trainings authors to update their material. I think we should do this task last. I've added it to the checklist.

Note that the alias already works, so maybe we can already start running linkcheck against 6.docs.plone.org.

[stevepiercy]

Per a conversation with @sneridagh, we realized that we should be pulling the Volto submodule from the 16.x.x branch now, instead of master. I've updated the task list accordingly.

[ksuess]

I would like to see redirect of 6.dev-docs.plone.org to 6.docs.plone.org prioritized. This because 6.docs.plone.org is still poorly indexed. And I think the reason is that 6.dev-docs.plone.org is still there and not permanently moved.

[stevepiercy]

I would like to see redirect of 6.dev-docs.plone.org to 6.docs.plone.org prioritized. This because 6.docs.plone.org is still poorly indexed. And I think the reason is that 6.dev-docs.plone.org is still there and not permanently moved.

I moved it up the list, but not into the "do now" list. I think it should be announced to the Community forum ahead of time to give people opportunity to fix their links now. Does that sound OK?

[ksuess]

I would like to see redirect of 6.dev-docs.plone.org to 6.docs.plone.org prioritized. This because 6.docs.plone.org is still poorly indexed. And I think the reason is that 6.dev-docs.plone.org is still there and not permanently moved.

I moved it up the list, but not into the "do now" list. I think it should be announced to the Community forum ahead of time to give people opportunity to fix their links now. Does that sound OK?

it does.

[ksuess]

+1 from me for 6.doc.plone.org for the official address of Plone 6 documentation (instead of docs.plone.org without sub sub domain) as this means bookmarks of new documentation stay valid in the future with 7.docs.plone.org, ….

[ksuess]

Page not found page:
my suggestion: #1400

New /404.html needs to be used as error page in web server configuration.

[ksuess]

+1 from me for 6.doc.plone.org for the official address of Plone 6 documentation (instead of docs.plone.org without sub sub domain) as this means bookmarks of new documentation stay valid in the future with 7.docs.plone.org, ….

and forget latest.docs.plone.org for the same reason: bookmarks and links to latest.docs.plone.org will be broken with Plone 7.

[stevepiercy]

and forget latest.docs.plone.org for the same reason: bookmarks and links to latest.docs.plone.org will be broken with Plone 7.

Also, now that I think of it, people can use docs instead of latest for the exact same purpose, and when Plone 6.1 or 7.0 get released, we will slap a banner on the 6.0 docs to go to the latest version of the docs with a link to docs that redirects to the actual latest version, whatever that becomes through time.

[stevepiercy]

Page not found page: my suggestion: #1400

New /404.html needs to be used as error page in web server configuration.

Added to checklist, and checked as answered the question regarding this.

[stevepiercy]

It's time to try to clean up the Documentation once again. @fredvd said I will be granted access to the machines that host Training and Documentation so that I can manage these things. However we need to make sure I know any history that should be preserved.

@pbauer @ksuess @polyester @spereverde @fredvd @ericof @MrTango please review the above plan, and let me know if there is anything that should be changed or considered:

#1140 (comment)

Thank you!

[fredvd]

@fredvd said I will be granted access to the machines that host Training and Documentation so that I can manage these things. However we need to make sure I know any history that should be preserved.

@pbauer @ksuess @polyester @spereverde @fredvd @ericof @MrTango please review the above plan, and let me know if there is anything that should be changed or considered:

To be more precise: I'll drive the project management for this one from the AI-team perspective, help you keep things moving forward and give you access to services/folders/hosts/accounts if that is required and you want to take the responsibility for those. ;-) Let's get this going.

[ksuess]

The plan sounds reasonable for me.

The broken search in 5.docs.plone.org is a blocker. During the short period of the switch docs.plone.org -> Plone 6 documentation it showed up that the search results are pointing to docs.plone.org/xy, which is wrong.

[fredvd]

The broken search in 5.docs.plone.org is a blocker. During the short period of the switch docs.plone.org -> Plone 6 documentation it showed up that the search results are pointing to docs.plone.org/xy, which is wrong.

I have tried in the past (and iirc succeeded) in seting up the stil live docs.plone.org build. I can repeat that, check with @polyester if that still works and if I'm not missing anything, so that we can deploy small fixes or changes to the current docs when we move them off the main docs.plone.org domain. But we shouldn't put more effort into that setup as necessary, but enough to keep it online for the next years. for reference.

[polyester]

@fredvd the setup still works, I'll update the description for Ubuntu 22.04 for list of required packages, the default Python version changed. But the blocker is the access to the Algolia search account - we don't have access, and Algolia's terms and conditions make it very vague if we can get a new account. They make it very hard to find their free offering for opensource docs projects anyway, much harder than it used to be.

If that becomes too annoying, we can remove the Algolia search and just provide Sphinx's less-than-pretty search for the 5 docs. And who knows, maybe create a knowledge bucket at Nuclia; at least we know them and they're a friendly bunch ;-)

[fredvd]

If that becomes too annoying, we can remove the Algolia search and just provide Sphinx's less-than-pretty search for the 5 docs. And who knows, maybe create a knowledge bucket at Nuclia; at least we know them and they're a friendly bunch ;-)

Sound like a plan. And it sounds like plan B, but maybe we should make this plan A with our limited resource available and forget about Algolia. Freebies come and go when VC demands their return on investment. Then we could even allow people to search in both docs at the same time, or at least show the same search interface and quality of results.

@ebrehault ?

[stevepiercy]

Personally I never liked the Algolia interface. I want a page of results that I can right-click and open in a new tab. Algolia's search results is limited to only a few items and clicking on a result keeps the focus in the same window. I would love to see it go away.

Nuclia would be my preferred choice, then Sphinx's default. Nuclia will be a GSoC project. I assume that Sphinx's default search would be not a lot of effort. If that is true, then I would opt to drop Algolia and use Sphinx for now, then adopt Nuclia to search Plone 5 and 6 docs for the GSoC project.

[polyester]

@fredvd @stevepiercy Algolia search is gone, https://5.docs.plone.org (which works as URL) and the currently-equivalent https://docs.plone.org now use the standard Sphinx search.
It was a bit of an effort, but mainly to get the buildout process working; buildout wants to get Zope 4.8.7 but that has a python < 3.9 limit in the wheel metadata, which doesn't help if you're building on 3.10. Making a local wheel with changed metadata works. It's a bit like !important in css - not pretty, but hey.

[polyester]

Note to future self: the only reason the 5 docs need a buildout of full Plone, which gets increasingly challenging as Python versions move on, is the plone.api docs and their use of autodoc. An escape hatch could be to point that sub-part of the 5 docs to the 6 docs.

[stevepiercy]

Note to future self: the only reason the 5 docs need a buildout of full Plone, which gets increasingly challenging as Python versions move on, is the plone.api docs and their use of autodoc.

In Plone 6 Documentation, I don't think we do a full buildout for any of the submodules that use autodoc, including plone.api and plone.restapi. Perhaps there is something from v6 that could be adapted to v5? There is some usefulness to git submodules.

An escape hatch could be to point that sub-part of the 5 docs to the 6 docs.

I don't know if you can add a banner announcement for just a section of the v5 docs, but that would be the most appropriate. Else something on the index of plone.api would have to do.

[stevepiercy]

After reviewing the checklist at the top of this issue, and checking off a few items, I think that the idea of setting up and tearing down a branch of 6-deploy would be a waste of time. It's a lot of effort for not much benefit, given that we have very little volunteer labor available to pull it off, and we would still need to do a lot of mop up of all the blood and guts with or without it.

I would like to get this entire checklist done either before or during Beethoven Sprint, May 15-19, 2023.

[stevepiercy]

This item is not possible, unless someone smarter than I knows how to make it work. I have crossed it off.

• Change Volto's submodule branch to be pulled into plone/documentation from master to 16.x.x (latest and stable).

As I understand it, a submodule points to only a single branch of a remote repository. In Volto we develop on master, then backport changes to 16.x.x, working on two branches, and toggling between branches in a submodule is not possible (or probably a complex process that I don't want to deal with).

When we cut the next major release of Plone and its documentation, then we can create a snapshot of older versions of Plone and Volto docs. This could be an issue for folks looking for older minor versions of Volto docs.

[stevepiercy]

The branch name in documentation should be 6.0, not 6, to be consistent with historic naming convention.

I have created a new branch 6.0 from 6-dev to allow automated testing and deployment.

[stevepiercy]

To make the task list easier to parse, I plopped all the remaining open tasks at the end of the task list, reordered them in a somewhat logical sequence, and assigned them by @ing the person. @polyester @ericof @fredvd

[stevepiercy]

"Merge 6-dev into 6.0." is not necessary. I merely need to set the default branch to 6.0 and announce that 6-dev is no longer used as the default branch.

[stevepiercy]

Post to community coming soon. Closing as complete. w00t!