To host versioned jenkins.io docs on docs.jenkins.io

[krisstern]

Service(s)

Helpdesk, jenkins.io

Summary

As one of the outcomes of the GSoC 2023 "Building jenkins.io with alternative tools" project we have come up with a draft of the versioned docs to be tested by the Jenkins community, especially the copy editors. As discussed previously, our desire is to have the Antora site hosted at docs.jennkins.io. The repo has been imported to https://github.com/jenkins-infra/jenkins-io-docs, and is ready to deploy. The Antora playbook needed for production is at https://github.com/jenkins-infra/jenkins-io-docs/blob/main/playbook/antora-playbook.yml. We have tested the setup locally which has been made possible with the local version of the Antora playbook and also the Makefile at the root.

Reproduction steps

No response

[lemeurherve]

@krisstern I'll take care of it.

Optional suggestion: WDYT of docs.jenkins.io as repository name instead of jenkins-io-docs?

[krisstern]

Sounds good @lemeurherve!

Sure, docs.jenkins.io would be a better name for the repo.

[lemeurherve]

Update: repository renamed, I need to write a runbook for contributors.jenkins.io and docs.jenkins.io.

[lemeurherve]

No progress since last update as other issues were prioritized.

[lemeurherve]

The CI part is now ready.

Next: add docs.jenkins.io to the publick8s cluster then add the deployment stage to the pipeline.

[lemeurherve]

Which teams should be affected to https://github.com/jenkins-infra/docs.jenkins.io instead of the individual collaborators currently set as admin?

Taking https://github.com/jenkins-infra/jenkins.io for inspiration, I propose to set the following teams & permissions:

1. https://github.com/orgs/jenkins-infra/teams/core as admin
2. https://github.com/orgs/jenkins-infra/teams/security as admin
3. https://github.com/orgs/jenkins-infra/teams/board as admin
4. https://github.com/orgs/jenkins-infra/teams/copy-editors as writer
5. Create a new "docs.jenkins.io" team dedicated to maintaining Antora, and add it as maintainer

WDYT @krisstern @MarkEWaite @kmartens27?

[lemeurherve]

https://docs.jenkins.io/ is live 🚀

Next: add the deployment stage to the pipeline.

[krisstern]

Which teams should be affected to https://github.com/jenkins-infra/docs.jenkins.io instead of the individual collaborators currently set as admin?

Taking https://github.com/jenkins-infra/jenkins.io for inspiration, I propose to set the following teams & permissions:

1. https://github.com/orgs/jenkins-infra/teams/core as admin
2. https://github.com/orgs/jenkins-infra/teams/security as admin
3. https://github.com/orgs/jenkins-infra/teams/board as admin
4. https://github.com/orgs/jenkins-infra/teams/copy-editors as writer
5. Create a new "docs.jenkins.io" team dedicated to maintaining Antora, and add it as maintainer

WDYT @krisstern @MarkEWaite @kmartens27?

Sounds like a good plan for me @lemeurherve! No objections from me.

[kmartens27]

Which teams should be affected to https://github.com/jenkins-infra/docs.jenkins.io instead of the individual collaborators currently set as admin?

Taking https://github.com/jenkins-infra/jenkins.io for inspiration, I propose to set the following teams & permissions:

1. https://github.com/orgs/jenkins-infra/teams/core as admin
2. https://github.com/orgs/jenkins-infra/teams/security as admin
3. https://github.com/orgs/jenkins-infra/teams/board as admin
4. https://github.com/orgs/jenkins-infra/teams/copy-editors as writer
5. Create a new "docs.jenkins.io" team dedicated to maintaining Antora, and add it as maintainer

WDYT @krisstern @MarkEWaite @kmartens27?

That sounds great to me @lemeurherve, thank you for all the work on this!

[MarkEWaite]

Which teams should be affected to https://github.com/jenkins-infra/docs.jenkins.io instead of the individual collaborators currently set as admin?

Taking https://github.com/jenkins-infra/jenkins.io for inspiration, I propose to set the following teams & permissions:

1. https://github.com/orgs/jenkins-infra/teams/core as admin
2. https://github.com/orgs/jenkins-infra/teams/security as admin
3. https://github.com/orgs/jenkins-infra/teams/board as admin
4. https://github.com/orgs/jenkins-infra/teams/copy-editors as writer
5. Create a new "docs.jenkins.io" team dedicated to maintaining Antora, and add it as maintainer

WDYT @krisstern @MarkEWaite @kmartens27?

That makes sense to me. Thanks!

[lemeurherve]

About the 5th point, I'm wondering if instead of A) creating a new team including Kriss, Kevin, Mark (current individuals with permission on this repo) we could B) use the existing team https://github.com/orgs/jenkins-infra/teams/docs as maintainers.

It would requires @krisstern to be added to this team in order to continue maintaining docs.jenkins.io repo.

WDYT?

(cc @daniel-beck & @dduportal as member of the docs team)

[MarkEWaite]

se the existing team https://github.com/orgs/jenkins-infra/teams/docs as maintainers.

That would be fine for me as well.

[dduportal]

About the 5th point, I'm wondering if instead of A) creating a new team including Kriss, Kevin, Mark (current individuals with permission on this repo) we could B) use the existing team https://github.com/orgs/jenkins-infra/teams/docs as maintainers.

It would requires @krisstern to be added to this team in order to continue maintaining docs.jenkins.io repo.

WDYT?

(cc @daniel-beck & @dduportal as member of the docs team)

Fine for me. It would grant the following permissions to Kris:

[lemeurherve]

I added @krisstern to the docs team and set all https://github.com/jenkins-infra/docs.jenkins.io permissions as follow:

[lemeurherve]

As noted in the plan, it would be wise to add a common prefix to the versioned doc branch names so we could target them with a pattern for branch protections. Something like "version-2.426.x" for example.

[dduportal]

version

stable-2.426.x ?

[dduportal]

https://docs.jenkins.io is live! As far as I can tell, we can close the issue. Many thanks y'all!

[krisstern]

Thank you everyone!