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, IRC 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.
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.
Noteare 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 ›