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.

Questions

1. Should we add docs.plone.org/latest as an alias for docs.plone.org/6? 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 5 Docs

• [ ] Create a snapshot of Plone 5 docs at docs.plone.org/5
• [ ] Update Plone 5 theme to have a banner across the top, similar to https://docs.python.org/3.5/. Alternatively update Plone 5 version switch to include Plone 6.

Set up Plone 6 Docs deployment

• [ ] Merge 6-dev into 6.
• [ ] Create an automatic deployment to docs.plone.org/6
• [ ] Update Netlify to build previews on the 6 branch as well as 6-dev.
• [ ] In conf.py under linkcheck_ignore, clean up any remaining commented links.
• [ ] Update base URL of sitemap.
• [ ] Check robots.txt.
• [ ] Ensure Matomo Analytics is tracking the correct URL.

Prepare each submodule

• [ ] Create a new branch, 6-deploy.
• [ ] In each conf.py, update the Intersphinx plone target to docs.plone.org/6.
• [ ] In plone/plone.api, update the URLs containing 6.dev-docs.plone.org to docs.plone.org/6.
• [ ] In plone/plone.restapi, update the URLs containing 6.dev-docs.plone.org to docs.plone.org/6.
• [ ] In plone/volto's README.md, update the URLs containing 6.dev-docs.plone.org to docs.plone.org/6.
• [ ] Update plone/documentation Makefile to pull in these submodules' new branches for testing.

Finally

• [ ] Merge each submodules' 6-deploy branch into master.
• [ ] Update plone/documentation Makefile to pull in these submodules' master branch for deployment.
• [ ] Deploy docs.plone.org/6.
• [ ] Redirect docs.plone.org to docs.plone.org/6.
• [ ] Redirect api.plone.org to docs.plone.org/6/plone.api.

[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: https://github.com/plone/documentation/pull/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:

https://github.com/plone/documentation/issues/1140#issue-1105004008

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.