cc6d4b0750
Since we are moving to matrix, lets drop reference to irc. I may have missed a few of these and I left the Zodbot SOP alone for now until we replace it with the new matrix one. Signed-off-by: Kevin Fenzi <kevin@scrye.com>
106 lines
3 KiB
Text
106 lines
3 KiB
Text
[[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.
|