#9892 Centralise and update Fedora infra and releng SOPs
Opened a year ago by mobrien. Modified 3 months ago

Describe what you would like us to do:


We have a number of out of date SOPs which are distributed across different places. These should be updated and moved to a central place.

Once the SOP is put into the new central place the old one should have its content removed and a link to the new doc put in its place to avoid multiple copies.

When do you need this to be done by? (YYYY/MM/DD)


This will be a long running ticket, where hopefully a number of people can contribute


Metadata Update from @mohanboddu:
- Issue tagged with: medium-gain, medium-trouble, ops

a year ago

A proposal for this is to have them on docs.fedoraproject.org under CPE. This would mean that infra and releng docs could be separate but grouped together under one umbrella.

This is only a suggestion so please voice opinions/concerns

21:12 <nb> mobrien so, I'm kind of -1 to putting all the docs under "CPE"
21:13 <nb> since CPE is just the Red Hat people. There are infra people who are not RH employees and thus not part of CPE

I would suggest making an infra section on docs.fedoraproject.org and moving everything there. I'm not sure how to handle the releng docs, if we want to put them there too, or create a separate releng section. Maybe make a "Infra+Releng" section on docs.fpo?

I would suggest making an infra section on docs.fedoraproject.org and moving everything there. I'm not sure how to handle the releng docs, if we want to put them there too, or create a separate releng section. Maybe make a "Infra+Releng" section on docs.fpo?

I like this idea too. It would benefit to have them together as there is crossover between the 2. If we were to have an Infra+Releng section then we could divide them under various sub headings.

Metadata Update from @kevin:
- Issue priority set to: Waiting on Assignee (was: Needs Review)

a year ago

Is there a list of the current locations that house the SOPs in their current form?

I'm with Nick here - I don't like the idea of putting the docs under CPE namespace as Fedora Infrastructure team is not a subset of CPE.

Thanks for your input @mizdebsk and @nb a better idea may be to have an infrastructure and releng tile on the homepage of docs.fp.o and have them housed here. I will mail the infra list as well to get more coverage on this.

Is there a list of the current locations that house the SOPs in their current form?

@ryanlerch there is no official list as such but these are some of the places, note there is more than sops here but it does give an idea as to how spread out the docs are

https://fedora-infra-docs.readthedocs.io/en/latest/
https://pagure.io/Fedora-Infra/howtos/tree/main
https://docs.pagure.org/releng/
https://fedoraproject.org/wiki/Infrastructure

As well as some google docs scattered about

One approach here would be to have several repos (i.e. documents). For
example, we could break up this document:
https://fedora-infra-docs.readthedocs.io/en/latest/ into

  • Fedora Infra Developers Guide
  • Fedora Infra Sysadmin's Guide (i.e. the SOPs)

We would probably have to create a new section on this page:
https://docs.fedoraproject.org/en-US/docs/
There is an "Engineering Teams" section that contains a couple links
to our docs (https://docs.fedoraproject.org/en-US/engineering/)
but a whole separate category on the main page is probably a good idea
here IMHO.

This new section would probably list documents like the newish Fedora
Accounts document
(https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other
user-facing documents about our apps too.

For the structure of the sources, something simple like repos labelled
"Documentation" in the fedora-infra github org might be the way to go,
like the source for the Fedora Accounts docs:
https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&type=Repositories

Thanks for your input @mizdebsk and @nb a better idea may be to have an infrastructure and releng tile on the homepage of docs.fp.o and have them housed here. I will mail the infra list as well to get more coverage on this.

Is there a list of the current locations that house the SOPs in their current form?

@ryanlerch there is no official list as such but these are some of the places, note there is more than sops here but it does give an idea as to how spread out the docs are

https://fedora-infra-docs.readthedocs.io/en/latest/

AFAICT, https://docs.pagure.org/infra-docs/ is the same as this readthedocs, but is not rebuilt as regularly. Should we just decomission the RTD one now to avoid further confusion here (i was confused).

Would like to help @mobrien with this when he is back from PTO

So, we now have: https://docs.fedoraproject.org//en-US/infra/ live and running.

Shall we close/take down pagure.io/infra-docs now?
And remove wiki pages/redirect to docs?

Then next steps are to focus on re-writing/cleaning up docs.fp.o site right?

Do we want to keep tracking work here?

cc: @zlopez

We should update the README for the old repository to point people to new one and add header to the docs that this is outdated documentation with link to a new one.

In other places the links should be updated to point to https://docs.fedoraproject.org//en-US/infra/

And we still need to port over the releng SOPs.

Regarding the rewrite and cleaning, we should probably track it on https://pagure.io/infra-docs-fpo instead of here.

I created a PR for the old infra docs repository adding links to new one to both README and index page https://pagure.io/infra-docs/pull-request/207

There is now an IMPORTANT section in both README and index that informs the readers about the new documentation with corresponding link.

We need a tile on the main docs.fp.o page for these as well to make them easy to find. Is this something you could do @pbokoc

I think it would be a good idea to move at this from the wiki to the new docs section as well. https://fedoraproject.org/wiki/Infrastructure/GettingStarted

@mobrien We are part of the Engineering Teams tile

[backlog_refinement]
Fedora Infrastructure docs already migrated to docs.fedoraproject.org
@pbokoc is currently working on migrating RelEng docs to docs.fedoraproject.org

[backlog refinement]
No new update on this one

Login to comment on this ticket.

Metadata
Boards 2
mini-initative Status: Backlog
ops Status: Backlog