Developing Standard Operating Procedures

When a new application is deployed in Fedora, it is critical that you add a standard operating procedure (SOP) for it. This documents how the application is deployed in Fedora. Consult the current sops and if one is missing, please add it.

You can modify this documentation or any of the current sops by making a pull request to the Pagure project.

Adding a Standard Operating Procedure

To add a standard operating procedure, create a new AsciiDoc file in the sop directory and then add it to the index file.

SOP text file names should use lowercase with dashes. Describe the service and end the page name with ".rst".

Stuff every SOP should have

Here’s the template for adding a new SOP:

= SOP Title

Provide a brief description of the SOP here.

== Contact Information

Owner::
  <usually, Fedora Infrastructure Team>
Contact::
  <stakeholder fas groups, individuals, matrix channels to find the action>
Location::
  <Relevant URIs, etc>
Servers::
  <affected machines>
Purpose::
  <a brief description of the SOPs purpose>

== Sections Describing Things

Put detailed information in these sections

=== A Helpful Sub-section

You can even have sub-sections.

==== A Sub-section of a sub-section

If a current SOP does not follow this general template, it should be updated to do so.

SOP Formatting

SOPs are written in AsciiDoc. To learn about the spec, read:

The format is somewhat simple if you remember a few key points:

  • Sections are prefixed by "=". The convention is that the number of "=" corresponds to level of section starting with title with only one.

  • Block like Note are delimited by "…​." bellow and above the text that should be in the note.

  • Use literal blocks for code and command sections. Add "…​." above and bellow the block. The "…​." is not the only delimiter you can use, there are multiple others. Like this:

    Literal blocks can be nested into lists (think a numbered sequence of steps)

. Log into the thing

. Run following commands
+
....
This text will be a literal block
....

. Log out of the thing.

  • For inline literals (commands, filenames, anything that wouldn’t make sense if translated, use your judgement) use backticks, like this:

    You should specify your Fedora username and ssh key in `~/.ssh/config` to make connecting
better.

  • When adding block in list use + between them for the correct indentation.

Want to help? Learn how to contribute to Fedora Docs ›