[[develop-sops]]
== 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
https://docs.fedoraproject.org/en-US/infra/sysadmin_guide/[sops] and if one
is missing, please add it.

You can modify this documentation or any of the current `sops` by making
a https://docs.pagure.org/pagure/usage/pull_requests.html[pull request]
to the https://pagure.io/infra-docs-fpo[Pagure project].

=== Adding a Standard Operating Procedure

To add a standard operating procedure, create a new
https://asciidoc-py.github.io/userguide.html[AsciiDoc] file in
the
https://pagure.io/infra-docs-fpo/blob/master/f/modules/sysadmin_guide/pages[sop
directory] and then add it to the
https://pagure.io/infra-docs-fpo/blob/master/f/modules/sysadmin_guide/nav.adoc[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 https://asciidoc-py.github.io/userguide.html[AsciiDoc].
To learn about the spec, read:

* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Quick
references]
* https://asciidoc-py.github.io/userguide.html[Full
Specification]

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 https://asciidoctor.org/docs/asciidoc-writers-guide/#delimited-blocks=[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.
