From dffc13fef2183e45a9bb2fc9fd0a94f92e3d87c5 Mon Sep 17 00:00:00 2001
From: Bussi Andrea <btabta@gmail.com>
Date: Mar 20 2022 15:27:26 +0000
Subject: [PATCH 1/4] Fix some typos and formatting.


Fix the note markup.

It was extending over all the rest of the page.

---

diff --git a/modules/ROOT/pages/sle.adoc b/modules/ROOT/pages/sle.adoc
index 7813abe..a928bcf 100644
--- a/modules/ROOT/pages/sle.adoc
+++ b/modules/ROOT/pages/sle.adoc
@@ -11,10 +11,10 @@ we will do to this extent.
 
 Fedora Infrastructure is a community team, involving volunteers as well as
 people employed by Red Hat to work on Fedora.
-However, despite the help of volunteers primary business hours are mostly
-aligned with the workk schedule of Red Hat. Normal hours should be seen as
-during Mondayy through Friday 1400 UTC to 2300 UTC with US national holidays and
-a 2 weeks end of year closure affecting staffing and response times.
+However, despite the help of volunteers, primary business hours are mostly
+aligned with the work schedule of Red Hat. Normal hours should be seen as
+Monday through Friday from 1400 UTC to 2300 UTC, excluding US national holidays
+and a 2 weeks end of year closure affecting staffing and response times.
 
 Services outside of primary business hours are done on call and depend on
 the availability of staff.
@@ -82,7 +82,7 @@ items rely on services in their own circle or a circle below them.
 . *Deprecated* services are ones which Fedora Infrastructure are no longer
   putting resources into. This may be because the project has completed its
   mission, the upstream software is dead, or the original reasons for the
-  product are available. Problems with these services will be looked at
+  service no longer exists. Problems with these services will be looked at
   during primary business hours. Responses may be mostly "Will Not Fix".
 
 == Limitations on Support
diff --git a/modules/developer_guide/pages/auth.adoc b/modules/developer_guide/pages/auth.adoc
index 583d309..fea8bcb 100644
--- a/modules/developer_guide/pages/auth.adoc
+++ b/modules/developer_guide/pages/auth.adoc
@@ -21,7 +21,9 @@ All new applications should use OpenID Connect for user authentication.
 ====
 Many existing applications use OpenID 2.0 and should eventually migrate
 to OpenID Connect.
-====OpenID Connect is an authentication layer built on top of OAuth 2.0
+====
+
+OpenID Connect is an authentication layer built on top of OAuth 2.0
 so to understand OpenID Connect you should first be familiar with OAuth
 2.0 and its various flows prior to learning about OpenID Connect.
 
@@ -42,7 +44,9 @@ https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest[requires
 that the "openid" scope is requested]. Failing to do so will result in
 undefined behavior. In the case of Ipsilon, you won't have access to the
 UserInfo or recieve an ID token.
-======= Libraries
+====
+
+=== Libraries
 
 ==== OAuthLib
 
diff --git a/modules/developer_guide/pages/code-style.adoc b/modules/developer_guide/pages/code-style.adoc
index 4f486fa..c729bc9 100644
--- a/modules/developer_guide/pages/code-style.adoc
+++ b/modules/developer_guide/pages/code-style.adoc
@@ -20,7 +20,9 @@ correctly styled before merging pull requests.
 There are a few PEP8 rules which will vary from project to project. For
 example, the maximum line length might vary. The test suite should
 enforce this.
-======== Enforcement
+====
+
+==== Enforcement
 
 Projects should automatically enforce code style. How a project does so
 is up to the maintainers, but several good options are documented here.
diff --git a/modules/developer_guide/pages/documentation.adoc b/modules/developer_guide/pages/documentation.adoc
index 3a0e832..c14c66e 100644
--- a/modules/developer_guide/pages/documentation.adoc
+++ b/modules/developer_guide/pages/documentation.adoc
@@ -24,7 +24,9 @@ Python documentation into HTML pages.
 Improving documentation is a great way to get involved in a project.
 When adding new documentation or cleaning up existing documentation,
 please follow the guidelines below.
-======= Style
+====
+
+=== Style
 
 Sphinx supports three different documentation styles. By default, Sphinx
 expects ReStructuredText. However, it has included an extension to
diff --git a/modules/developer_guide/pages/fedmsg.adoc b/modules/developer_guide/pages/fedmsg.adoc
index dd2aff9..671bf1c 100644
--- a/modules/developer_guide/pages/fedmsg.adoc
+++ b/modules/developer_guide/pages/fedmsg.adoc
@@ -11,7 +11,9 @@ they're interested in receiving.
 fedmsg does not guarantee message delivery. Messages will be lost and
 your application should never depend on the reliable delivery of fedmsgs
 to function.
-======= Topics
+====
+
+=== Topics
 
 ==== Existing Topics
 
diff --git a/modules/developer_guide/pages/frameworks.adoc b/modules/developer_guide/pages/frameworks.adoc
index 3f96e38..f6532a9 100644
--- a/modules/developer_guide/pages/frameworks.adoc
+++ b/modules/developer_guide/pages/frameworks.adoc
@@ -21,7 +21,9 @@ For historical reasons, you may find applications that don't use Flask.
 Other frameworks currently in use include
 https://www.djangoproject.com/[Django] and
 http://docs.pylonsproject.org/projects/pyramid/en/latest/[Pyramid].
-====Flask is designed to be extensible, so it's common to use extensions
+====
+
+Flask is designed to be extensible, so it's common to use extensions
 with the core flask library. A few common extensions are documented
 below.
 
diff --git a/modules/developer_guide/pages/messaging.adoc b/modules/developer_guide/pages/messaging.adoc
index c277bcf..826516b 100644
--- a/modules/developer_guide/pages/messaging.adoc
+++ b/modules/developer_guide/pages/messaging.adoc
@@ -48,7 +48,7 @@ bindings.
 The message broker can use https://www.rabbitmq.com/vhosts.html[virtual
 hosts] to allow multiple applications to use the broker. The general
 purpose publish-subscribe virtual host is called `/pubsub` and has its
-authorization policy is outlined below. If your application is using a
+authorization policy outlined below. If your application is using a
 different virtual host for private messaging (for example, your
 application uses Celery), different authorization rules apply.
 
@@ -67,7 +67,9 @@ Because AMQP clients don't have permission to create objects, you need
 to set
 https://fedora-messaging.readthedocs.io/en/stable/configuration.html#passive-declares[passive_declares
 = true] or you will get 403 Permission Denied errors.
-====Users, exchanges, queues, bindings, and
+====
+
+Users, exchanges, queues, bindings, and
 https://www.rabbitmq.com/vhosts.html[virtual hosts] other objects are
 managed in the broker using the Fedora Infrastructure Ansible project
 and must be declared there.
diff --git a/modules/developer_guide/pages/security_policy.adoc b/modules/developer_guide/pages/security_policy.adoc
index 94732a3..358b414 100644
--- a/modules/developer_guide/pages/security_policy.adoc
+++ b/modules/developer_guide/pages/security_policy.adoc
@@ -69,7 +69,7 @@ call MUST be protected against cross-site request forgery.
 
 The application MUST set the Secure flag on any cookies it sets if it is
 not in a development mode. The application MUST set the httpOnly flag on
-any cookiees it sets. The application SHOULD NOT set a Domain parameter
+any cookies it sets. The application SHOULD NOT set a Domain parameter
 in any cookies it sets, if it does set the Domain, its value MUST be
 identical to the exact Host requested.
 
@@ -81,16 +81,16 @@ inserted into a frame. Setting anything else than `DENY` is a flag for
 review. The application MUST set the `X-Xss-Protection` header, and the
 value MUST be `1; mode=block`. The application MUST set the
 `X-Content-Type-Options` header, and the value MUST be `nosniff`. The
-application MUST set the `\`Referrer-Policy`[.title-ref]##_ header, and
+application MUST set the `Referrer-Policy`[.title-ref]## header, and
 the value MUST be ##[.title-ref]##no-referrer##[.title-ref]## or
-##[.title-ref]##same-origin##`.
+##[.title-ref]##same-origin##.
 
-The application MUST set the `\`Content-Security-Policy`[.title-ref]##_
+The application MUST set the `Content-Security-Policy`[.title-ref]##
 header and MUST set at least
 ##[.title-ref]##default-src##[.title-ref]##. The content security MUST
 NOT allow any origins other than ##[.title-ref]##'none'##[.title-ref]##,
 ##[.title-ref]##'self'##[.title-ref]##, any of the explicitly approved
-origins (listed below) or ##[.title-ref]##nonce-$nonce##`. Any nonces
+origins (listed below) or ##[.title-ref]##nonce-$nonce##. Any nonces
 used for the content security policy MUST be generated via a
 Cryptographically Secure PRNG.
 
diff --git a/modules/developer_guide/pages/sops.adoc b/modules/developer_guide/pages/sops.adoc
index 2e92330..23d88cb 100644
--- a/modules/developer_guide/pages/sops.adoc
+++ b/modules/developer_guide/pages/sops.adoc
@@ -74,7 +74,7 @@ Specification]
 
 The format is somewhat simple if you remember a few key points:
 
-* Sections are deliniated by underlined texts. The convention is:
+* Sections are delineated by underlined texts. The convention is:
 ** Title has "=" above and below the title text, at least as many
 columns as the title itself.
 ** Top level sections are underlined by "===" - at least as many columns
@@ -82,7 +82,7 @@ as the section title in the line above.
 ** Second level sections are underlined by "---"
 ** Any of
 `! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ \` { | } ~` are
-valid section deliniators. If you need more than two section levels,
+valid section delineators. If you need more than two section levels,
 choose between them but be sure to be consistent.
 * Indents are significant. Only indent for things like block quotes,
 nested lists etc. Match the tabstop of the document you are editing.

From 254dd5f50d6cd76597844c8a2bb248d0522398cb Mon Sep 17 00:00:00 2001
From: Bussi Andrea <btabta@gmail.com>
Date: Mar 20 2022 15:28:14 +0000
Subject: [PATCH 2/4] Update the IRC to libera.chat.


---

diff --git a/modules/sysadmin_guide/pages/orientation.adoc b/modules/sysadmin_guide/pages/orientation.adoc
index 4240637..771bad6 100644
--- a/modules/sysadmin_guide/pages/orientation.adoc
+++ b/modules/sysadmin_guide/pages/orientation.adoc
@@ -53,7 +53,7 @@ that but $ADMIN will be and he should be here in about 3 hours".
 The team itself is generally friendly and honest. Don't be afraid to
 disagree with someone, even if you're new and they're an old timer. Just
 make sure you ask yourself what is important to you and make sure to
-provide data, we like that. We generally communicate on irc.freenode.net
+provide data, we like that. We generally communicate on libera.chat
 in #fedora-admin. We have our weekly meetings on IRC and its the
 quickest way to get in touch with everyone. Secondary to that we use the
 mailing list. After that its our ticketing system and

From d9066bb5537116d687628d8fa3bdb0ca84590d41 Mon Sep 17 00:00:00 2001
From: Bussi Andrea <btabta@gmail.com>
Date: Mar 20 2022 15:28:32 +0000
Subject: [PATCH 3/4] Fix some small typos.


---

diff --git a/modules/sysadmin_guide/pages/accountdeletion.adoc b/modules/sysadmin_guide/pages/accountdeletion.adoc
index 39ce36a..e4db222 100644
--- a/modules/sysadmin_guide/pages/accountdeletion.adoc
+++ b/modules/sysadmin_guide/pages/accountdeletion.adoc
@@ -173,7 +173,7 @@ username/groupname rather than UID/GID.
 [WARNING]
 .Warning
 ====
-Needs more eyes This list may not be complete.
+Needs more eyes. This list may not be complete.
 ====
 
 * Check the databases for koji, pkgdb, and bodhi for occurrences of
@@ -200,7 +200,7 @@ themselves b/c they're getting a new home directory).
 [WARNING]
 .Warning
 ====
-Needs more eyes This list may not be complete.
+Needs more eyes. This list may not be complete.
 ====
 * grep through ansible for occurrences of the group name.
 * Check for group-members,group-admins,group-sponsors@fedoraproject.org
@@ -223,7 +223,7 @@ reused.
 .Note
 ====
 Recommended to rename instead When not strictly necessary to purge all
-traces of an account, it's highlyrecommended to rename the user or group
+traces of an account, it's highly recommended to rename the user or group
 to something like DELETED_oldusername instead of deleting. This avoids
 the problems and additional checking that we have to do below.
 ====
@@ -232,8 +232,10 @@ the problems and additional checking that we have to do below.
 [WARNING]
 .Warning
 ====
-Needs more eyes This list may be incomplete. Needs more people to look
-at this and find places that may need to be updated
+Needs more eyes.
+
+This list may be incomplete. Needs more people to look
+at this and find places that may need to be updated.
 ====
 * Check everything for the #Rename Accounts case.
 * Figure out what boxes a user may have had access to in the past. This
@@ -257,7 +259,7 @@ Any files owned by that uid must be reassigned to another user or::
 .Warning
 ====
 What to do about backups? Backups pose a special problem as they may
-contain the uid that's being removed. Need to decide how to handle this
+contain the uid that's being removed. Need to decide how to handle this.
 ====
 * Add other places to check here
 
@@ -266,8 +268,10 @@ contain the uid that's being removed. Need to decide how to handle this
 [WARNING]
 .Warning
 ====
-Needs more eyes This list may be incomplete. Needs more people to look
-at this and find places that may need to be updated
+Needs more eyes.
+
+This list may be incomplete. Needs more people to look
+at this and find places that may need to be updated.
 ====
 * Check everything for the #Rename Groups case.
 * Figure out what boxes may have had files owned by that group. This
@@ -289,6 +293,6 @@ removed.
 .Warning
 ====
 What to do about backups? Backups pose a special problem as they may
-contain the gid that's being removed. Need to decide how to handle this
+contain the gid that's being removed. Need to decide how to handle this.
 ====
 * Add other places to check here
diff --git a/modules/sysadmin_guide/pages/database.adoc b/modules/sysadmin_guide/pages/database.adoc
index 4fb8e8a..fc09315 100644
--- a/modules/sysadmin_guide/pages/database.adoc
+++ b/modules/sysadmin_guide/pages/database.adoc
@@ -161,7 +161,7 @@ from pg_database order by xids_remaining;
 
 == Restart Procedure
 
-If the database server needs to be restarted it should come back on it's
+If the database server needs to be restarted it should come back on its
 own. Otherwise each service on it can be restarted:
 
 ....
diff --git a/modules/sysadmin_guide/pages/orientation.adoc b/modules/sysadmin_guide/pages/orientation.adoc
index 771bad6..f3cb84d 100644
--- a/modules/sysadmin_guide/pages/orientation.adoc
+++ b/modules/sysadmin_guide/pages/orientation.adoc
@@ -56,7 +56,7 @@ make sure you ask yourself what is important to you and make sure to
 provide data, we like that. We generally communicate on libera.chat
 in #fedora-admin. We have our weekly meetings on IRC and its the
 quickest way to get in touch with everyone. Secondary to that we use the
-mailing list. After that its our ticketing system and
+mailing list. After that it's our ticketing system and
 talk.fedoraproject.org.
 
 _Welcome to the team!_
@@ -110,8 +110,8 @@ https://pagure.io/fedora-infrastructure/issues
 When you find a ticket that interests you contact your sponsor or the
 ticket owner and offer help. While you're getting used to the way things
 work, don't be offput by someone saying no or you can't work on that. It
-happens, sometimes its a security thing, sometimes its a "I'm half way
-through it and I'm not happy with where it is thing." Just move on to
+happens, sometimes it's a security thing, sometimes it's a "I'm half way
+through it and I'm not happy with where it is" thing. Just move on to
 the next ticket and go from there.
 
 Also don't be surprised if some of the work involved includes testing on
@@ -121,7 +121,7 @@ no access at all. Doing this kind of work is a sure fire way to get in
 to more groups and get more involved. Don't be afraid to take on tasks
 you don't already know how to do. But don't take on something you know
 you won't be able to do. Ask for help when you need it and keep in
-contact with your sponsor so you know
+contact with your sponsor.
 
 == Ansible
 
diff --git a/modules/sysadmin_guide/pages/outage.adoc b/modules/sysadmin_guide/pages/outage.adoc
index 9d0e0b2..7cacc28 100644
--- a/modules/sysadmin_guide/pages/outage.adoc
+++ b/modules/sysadmin_guide/pages/outage.adoc
@@ -168,7 +168,7 @@ be pushed to show the services are restored.
 
 [IMPORTANT]
 ====
-Additionally update any SOP's that may have changed in the course of the outage
+Additionally update any SOP's that may have changed in the course of the outage.
 ====
 
 === Unplanned Outage
diff --git a/modules/sysadmin_guide/pages/status-fedora.adoc b/modules/sysadmin_guide/pages/status-fedora.adoc
index 77862a7..4a55c14 100644
--- a/modules/sysadmin_guide/pages/status-fedora.adoc
+++ b/modules/sysadmin_guide/pages/status-fedora.adoc
@@ -81,10 +81,10 @@ and relocate the swarm.
 ....
 +
 ____
-* Note that OutageFinish is optional, but should really only be ommited
+* Note that OutageFinish is optional, but should really only be omitted
 if the projected / or actual outage time is unknown.
-* When providing dated, keep the timezone offset at +0000 / UTC
-datetimes
+* When providing a date, keep the timezone offset at +0000 / UTC
+datetimes.
 ____
 
 === Moving an outage
@@ -129,7 +129,7 @@ moving outages)
 === Publishing theme changes
 
 If your changes involve changes to the theme, run the following command
-to upload everything content and theme changes to the live server:
+to upload everything (content and theme changes) to the live server:
 
 ....
 make upload-theme
@@ -153,8 +153,8 @@ In a different terminal upload requested file to AWS S3 bucket:
 echo SOME_VALUE >myfile
 aws --profile statusfpo s3 cp myfile s3://status.fedoraproject.org/.well-known/acme-challenge/SOME_FILE
 ....
-. Verify that uploaded file is available under the rigt URL. If previous
-certificate already expired you may need to run curl with -k option:
+. Verify that uploaded file is available under the right URL. If the previous
+certificate is already expired, you may need to run curl with -k option:
 +
 ....
 curl -kL http://www.fedorastatus.org/.well-known/acme-challenge/SOME_FILE

From 3ced0ea55e09c43b25347abc21cc86aba5c31b9d Mon Sep 17 00:00:00 2001
From: Bussi Andrea <btabta@gmail.com>
Date: Mar 20 2022 18:09:33 +0000
Subject: [PATCH 4/4] Fix two missing link.


---

diff --git a/modules/developer_guide/pages/writing-tests..adoc b/modules/developer_guide/pages/writing-tests..adoc
deleted file mode 100644
index f7b021a..0000000
--- a/modules/developer_guide/pages/writing-tests..adoc
+++ /dev/null
@@ -1,269 +0,0 @@
-== Tests
-
-Tests make development easier for both veteran project contributors and
-newcomers alike. Most projects use the
-https://docs.python.org/3.6/library/unittest.html[unittest] framework
-for tests so you should familiarize yourself with this framework.
-
-[NOTE]
-.Note
-====
-Writing tests can be a great way to get involved with a project. It's an
-opportunity to get familiar with the codebase and the code submission
-and review process. Check the project's code coverage and write a test
-for a piece of code missing coverage!
-====Patches should be accompanied by one or more tests to demonstrate
-the feature or bugfix works. This makes the review process much easier
-since it allows the reviewer to run your code with very little effort,
-and it lets developers know when they break your code.
-
-=== Test Organization
-
-Having a standard test layout makes it easy to find tests. When adding
-new tests, follow the following guidelines:
-
-[arabic]
-. Each module in the application should have a corresponding test
-module. These modules should be organized in the test package to mirror
-the package they test. That is, if the package contains the
-`<package>/server/push.py` module, the test module should be in a module
-called `<test_root>/server/test_push.py`.
-. Within each test module, follow the
-https://docs.python.org/3.6/library/unittest.html#organizing-test-code[unittest
-code organization guidelines].
-. Include documentation blocks for each test case that explain the goal
-of the test.
-. Avoid using mock unless absolutely necessary. It's easy to write tests
-using mock that only assert that mock works as expected. When testing
-code that makes HTTP requests, consider using
-https://pypi.python.org/pypi/vcrpy[vcrpy].
-
-[NOTE]
-.Note
-====
-You may find projects that do not follow this test layout. In those
-cases, consider re-organizing the tests to follow the layout described
-here and follow the established conventions for that project until that
-happens.
-======= Test Runners
-
-Projects should include a way to run the tests with ease locally and the
-steps to run the tests should be documented. This should be the same way
-the continuous integration (Jenkins, TravisCI, etc.) tool runs the
-tests.
-
-There are many test runners available that can discover
-https://docs.python.org/3.6/library/unittest.html[unittest] based tests.
-These include:
-
-* https://docs.python.org/3.6/library/unittest.html[unittest] itself via
-`python -m unittest discover`
-* http://docs.pytest.org/en/latest/contents.html[pytest]
-* http://nose2.readthedocs.io/en/latest/[nose2]
-
-Projects should choose whichever runner best suits them.
-
-[NOTE]
-.Note
-====
-You may find projects using the
-https://nose.readthedocs.io/en/latest/[nose] test runner. nose is in
-maintenance mode and, according to their documentation, will likely
-cease without a new maintainer. They recommend using
-https://docs.python.org/3.6/library/unittest.html[unittest],
-http://docs.pytest.org/en/latest/contents.html[pytest], or
-http://nose2.readthedocs.io/en/latest/[nose2].
-====[[tox-config]]
-=== Tox
-
-https://pypi.python.org/pypi/tox[Tox] is an easy way to run your
-project's tests (using a Python test runner) using multiple Python
-interpreters. It also allows you to define arbitrary test environments,
-so it's an excellent place to run the code style tests and to ensure the
-project's documentation builds without errors or warnings.
-
-Here's an example `tox.ini` file that runs a project's unit tests in
-Python 2.7, Python 3.4, Python 3.5, and Python 3.6. It also runs
-https://pypi.python.org/pypi/flake8[flake8] on the entire codebase and
-builds the documentation with the "warnings treated as errors" Sphinx
-flag enabled. Finally, it enforces 100% coverage on lines edited by new
-patches using https://pypi.org/project/diff-cover/[diff-cover]:
-
-....
-[tox]
-envlist = py27,py34,py35,py36,lint,diff-cover,docs
-# If the user is missing an interpreter, don't fail
-skip_missing_interpreters = True
-
-[testenv]
-deps =
-    -rtest-requirements.txt
-# Substitute your test runner of choice
-commands =
-    py.test
-# When running in OpenShift you don't have a username, so expanduser
-# won't work. If you are running your tests in CentOS CI, this line is
-# important so the tests can pass there, otherwise tox will fail to find
-# a home directory when looking for configuration files.
-passenv = HOME
-
-[testenv:diff-cover]
-deps =
-    diff-cover
-commands =
-    diff-cover coverage.xml --compare-branch=origin/master --fail-under=100
-
-[testenv:docs]
-changedir = docs
-deps =
-    sphinx
-    sphinxcontrib-httpdomain
-    -rrequirements.txt
-whitelist_externals =
-    mkdir
-    sphinx-build
-commands=
-    mkdir -p _static
-    sphinx-build -W -b html -d {envtmpdir}/doctrees .  _build/html
-
-[testenv:lint]
-deps =
-    flake8 > 3.0
-commands =
-    python -m flake8 {posargs}
-
-[flake8]
-show-source = True
-max-line-length = 100
-exclude = .git,.tox,dist,*egg
-....
-
-=== Coverage
-
-https://pypi.python.org/pypi/coverage/[coverage] is a good way to
-collect test coverage statistics.
-http://docs.pytest.org/en/latest/contents.html[pytest] has a
-https://pypi.python.org/pypi/pytest-cov[pytest-cov] plugin that
-integrates with https://pypi.python.org/pypi/coverage/[coverage] and
-https://pypi.python.org/pypi/nose-cov[nose-cov] provides integration for
-the https://nose.readthedocs.io/en/latest/[nose] test runner.
-https://pypi.org/project/diff-cover/[diff-cover] can be used to ensure
-that all lines edited in a patch have coverage.
-
-It's possible (and recommended) to have the test suite fail if the
-coverage percentage goes down. This example `.coveragerc`:
-
-....
-[run]
-# Track what conditional branches are covered.
-branch = True
-include =
-    my_python_package/*
-
-[report]
-# Fail if the coverage is not 100%
-fail_under = 100
-# Display results with up 1/100th of a percent accuracy.
-precision = 2
-exclude_lines =
-    pragma: no cover
-
-    # Don't complain if tests don't hit defensive assertion code
-    raise AssertionError
-    raise NotImplementedError
-
-    if __name__ == .__main__.:
-omit =
-    my_python_package/tests/*
-....
-
-To configure `pytest` to collect coverage data on your project, edit
-`setup.cfg` and add this block, substituting `yourpackage` with the name
-of the Python package you are measuring coverage on:
-
-....
-[tool:pytest]
-addopts = --cov-config .coveragerc --cov=yourpackage --cov-report term --cov-report xml --cov-report html
-....
-
-causes coverage (and any test running plugins using coverage) to fail if
-the coverage level is not 100%. New projects should enforce 100% test
-coverage. Existing projects should ensure test coverage does not drop to
-accept a pull request and should increase the minimum test coverage
-until it is 100%.
-
-[NOTE]
-.Note
-====
-https://pypi.python.org/pypi/coverage/[coverage] has great
-https://coverage.readthedocs.io/en/coverage-4.3.4/excluding.html[exclusion]
-support, so you can exclude individual lines, conditional branches,
-functions, classes, and whole source files from your coverage report. If
-you have code that doesn't make sense to have tests for, you can exclude
-it from your coverage report. Remember to leave a comment explaining why
-it's excluded!
-======= Licenses
-
-The https://pypi.org/project/liccheck/[liccheck] checker can verify that
-every dependency in your project has an acceptable license. The
-dependencies are checked recursively.
-
-The licenses are validated against a set of acceptable licenses that you
-define in a file called `.license_strategy.ini` in your project
-directory. Here is an example of such a file, that would accept Free
-licenses:
-
-....
-[Licenses]
-authorized_licenses:
-        bsd
-        new bsd
-        simplified bsd
-        apache
-        apache 2.0
-        apache software
-        gnu lgpl
-        gpl v2
-        gpl v3
-        lgpl with exceptions or zpl
-        isc
-        isc license (iscl)
-        mit
-        python software foundation
-        zpl 2.1
-....
-
-The verification is case-insensitive, and is done on both the `license`
-and the `classifiers` metadata fields. See
-https://pypi.org/project/liccheck/[liccheck]'s documentation for more
-details.
-
-You can automate the license check with the following snippet in your
-`tox.ini` file:
-
-....
-[testenv:licenses]
-deps =
-    liccheck
-commands =
-    liccheck -s .license_strategy.ini
-....
-
-Remember to add `licenses` to your Tox `envlist`.
-
-=== Security
-
-The https://pypi.org/project/bandit/[bandit] checker is designed to find
-common security issues in Python code.
-
-You can add it to the tests run by Tox by adding the following snippet
-to your `tox.ini` file:
-
-....
-[testenv:bandit]
-deps = bandit
-commands =
-    bandit -r your_project/ -x your_project/tests/ -ll
-....
-
-Remember to add `bandit` to your Tox `envlist`.
diff --git a/modules/developer_guide/pages/writing-tests.adoc b/modules/developer_guide/pages/writing-tests.adoc
new file mode 100644
index 0000000..f7b021a
--- /dev/null
+++ b/modules/developer_guide/pages/writing-tests.adoc
@@ -0,0 +1,269 @@
+== Tests
+
+Tests make development easier for both veteran project contributors and
+newcomers alike. Most projects use the
+https://docs.python.org/3.6/library/unittest.html[unittest] framework
+for tests so you should familiarize yourself with this framework.
+
+[NOTE]
+.Note
+====
+Writing tests can be a great way to get involved with a project. It's an
+opportunity to get familiar with the codebase and the code submission
+and review process. Check the project's code coverage and write a test
+for a piece of code missing coverage!
+====Patches should be accompanied by one or more tests to demonstrate
+the feature or bugfix works. This makes the review process much easier
+since it allows the reviewer to run your code with very little effort,
+and it lets developers know when they break your code.
+
+=== Test Organization
+
+Having a standard test layout makes it easy to find tests. When adding
+new tests, follow the following guidelines:
+
+[arabic]
+. Each module in the application should have a corresponding test
+module. These modules should be organized in the test package to mirror
+the package they test. That is, if the package contains the
+`<package>/server/push.py` module, the test module should be in a module
+called `<test_root>/server/test_push.py`.
+. Within each test module, follow the
+https://docs.python.org/3.6/library/unittest.html#organizing-test-code[unittest
+code organization guidelines].
+. Include documentation blocks for each test case that explain the goal
+of the test.
+. Avoid using mock unless absolutely necessary. It's easy to write tests
+using mock that only assert that mock works as expected. When testing
+code that makes HTTP requests, consider using
+https://pypi.python.org/pypi/vcrpy[vcrpy].
+
+[NOTE]
+.Note
+====
+You may find projects that do not follow this test layout. In those
+cases, consider re-organizing the tests to follow the layout described
+here and follow the established conventions for that project until that
+happens.
+======= Test Runners
+
+Projects should include a way to run the tests with ease locally and the
+steps to run the tests should be documented. This should be the same way
+the continuous integration (Jenkins, TravisCI, etc.) tool runs the
+tests.
+
+There are many test runners available that can discover
+https://docs.python.org/3.6/library/unittest.html[unittest] based tests.
+These include:
+
+* https://docs.python.org/3.6/library/unittest.html[unittest] itself via
+`python -m unittest discover`
+* http://docs.pytest.org/en/latest/contents.html[pytest]
+* http://nose2.readthedocs.io/en/latest/[nose2]
+
+Projects should choose whichever runner best suits them.
+
+[NOTE]
+.Note
+====
+You may find projects using the
+https://nose.readthedocs.io/en/latest/[nose] test runner. nose is in
+maintenance mode and, according to their documentation, will likely
+cease without a new maintainer. They recommend using
+https://docs.python.org/3.6/library/unittest.html[unittest],
+http://docs.pytest.org/en/latest/contents.html[pytest], or
+http://nose2.readthedocs.io/en/latest/[nose2].
+====[[tox-config]]
+=== Tox
+
+https://pypi.python.org/pypi/tox[Tox] is an easy way to run your
+project's tests (using a Python test runner) using multiple Python
+interpreters. It also allows you to define arbitrary test environments,
+so it's an excellent place to run the code style tests and to ensure the
+project's documentation builds without errors or warnings.
+
+Here's an example `tox.ini` file that runs a project's unit tests in
+Python 2.7, Python 3.4, Python 3.5, and Python 3.6. It also runs
+https://pypi.python.org/pypi/flake8[flake8] on the entire codebase and
+builds the documentation with the "warnings treated as errors" Sphinx
+flag enabled. Finally, it enforces 100% coverage on lines edited by new
+patches using https://pypi.org/project/diff-cover/[diff-cover]:
+
+....
+[tox]
+envlist = py27,py34,py35,py36,lint,diff-cover,docs
+# If the user is missing an interpreter, don't fail
+skip_missing_interpreters = True
+
+[testenv]
+deps =
+    -rtest-requirements.txt
+# Substitute your test runner of choice
+commands =
+    py.test
+# When running in OpenShift you don't have a username, so expanduser
+# won't work. If you are running your tests in CentOS CI, this line is
+# important so the tests can pass there, otherwise tox will fail to find
+# a home directory when looking for configuration files.
+passenv = HOME
+
+[testenv:diff-cover]
+deps =
+    diff-cover
+commands =
+    diff-cover coverage.xml --compare-branch=origin/master --fail-under=100
+
+[testenv:docs]
+changedir = docs
+deps =
+    sphinx
+    sphinxcontrib-httpdomain
+    -rrequirements.txt
+whitelist_externals =
+    mkdir
+    sphinx-build
+commands=
+    mkdir -p _static
+    sphinx-build -W -b html -d {envtmpdir}/doctrees .  _build/html
+
+[testenv:lint]
+deps =
+    flake8 > 3.0
+commands =
+    python -m flake8 {posargs}
+
+[flake8]
+show-source = True
+max-line-length = 100
+exclude = .git,.tox,dist,*egg
+....
+
+=== Coverage
+
+https://pypi.python.org/pypi/coverage/[coverage] is a good way to
+collect test coverage statistics.
+http://docs.pytest.org/en/latest/contents.html[pytest] has a
+https://pypi.python.org/pypi/pytest-cov[pytest-cov] plugin that
+integrates with https://pypi.python.org/pypi/coverage/[coverage] and
+https://pypi.python.org/pypi/nose-cov[nose-cov] provides integration for
+the https://nose.readthedocs.io/en/latest/[nose] test runner.
+https://pypi.org/project/diff-cover/[diff-cover] can be used to ensure
+that all lines edited in a patch have coverage.
+
+It's possible (and recommended) to have the test suite fail if the
+coverage percentage goes down. This example `.coveragerc`:
+
+....
+[run]
+# Track what conditional branches are covered.
+branch = True
+include =
+    my_python_package/*
+
+[report]
+# Fail if the coverage is not 100%
+fail_under = 100
+# Display results with up 1/100th of a percent accuracy.
+precision = 2
+exclude_lines =
+    pragma: no cover
+
+    # Don't complain if tests don't hit defensive assertion code
+    raise AssertionError
+    raise NotImplementedError
+
+    if __name__ == .__main__.:
+omit =
+    my_python_package/tests/*
+....
+
+To configure `pytest` to collect coverage data on your project, edit
+`setup.cfg` and add this block, substituting `yourpackage` with the name
+of the Python package you are measuring coverage on:
+
+....
+[tool:pytest]
+addopts = --cov-config .coveragerc --cov=yourpackage --cov-report term --cov-report xml --cov-report html
+....
+
+causes coverage (and any test running plugins using coverage) to fail if
+the coverage level is not 100%. New projects should enforce 100% test
+coverage. Existing projects should ensure test coverage does not drop to
+accept a pull request and should increase the minimum test coverage
+until it is 100%.
+
+[NOTE]
+.Note
+====
+https://pypi.python.org/pypi/coverage/[coverage] has great
+https://coverage.readthedocs.io/en/coverage-4.3.4/excluding.html[exclusion]
+support, so you can exclude individual lines, conditional branches,
+functions, classes, and whole source files from your coverage report. If
+you have code that doesn't make sense to have tests for, you can exclude
+it from your coverage report. Remember to leave a comment explaining why
+it's excluded!
+======= Licenses
+
+The https://pypi.org/project/liccheck/[liccheck] checker can verify that
+every dependency in your project has an acceptable license. The
+dependencies are checked recursively.
+
+The licenses are validated against a set of acceptable licenses that you
+define in a file called `.license_strategy.ini` in your project
+directory. Here is an example of such a file, that would accept Free
+licenses:
+
+....
+[Licenses]
+authorized_licenses:
+        bsd
+        new bsd
+        simplified bsd
+        apache
+        apache 2.0
+        apache software
+        gnu lgpl
+        gpl v2
+        gpl v3
+        lgpl with exceptions or zpl
+        isc
+        isc license (iscl)
+        mit
+        python software foundation
+        zpl 2.1
+....
+
+The verification is case-insensitive, and is done on both the `license`
+and the `classifiers` metadata fields. See
+https://pypi.org/project/liccheck/[liccheck]'s documentation for more
+details.
+
+You can automate the license check with the following snippet in your
+`tox.ini` file:
+
+....
+[testenv:licenses]
+deps =
+    liccheck
+commands =
+    liccheck -s .license_strategy.ini
+....
+
+Remember to add `licenses` to your Tox `envlist`.
+
+=== Security
+
+The https://pypi.org/project/bandit/[bandit] checker is designed to find
+common security issues in Python code.
+
+You can add it to the tests run by Tox by adding the following snippet
+to your `tox.ini` file:
+
+....
+[testenv:bandit]
+deps = bandit
+commands =
+    bandit -r your_project/ -x your_project/tests/ -ll
+....
+
+Remember to add `bandit` to your Tox `envlist`.
diff --git a/modules/sysadmin_guide/pages/index.adoc b/modules/sysadmin_guide/pages/index.adoc
index 9c0bef9..8cba07e 100644
--- a/modules/sysadmin_guide/pages/index.adoc
+++ b/modules/sysadmin_guide/pages/index.adoc
@@ -40,8 +40,8 @@ have read-only access). Apprentice can, however, contribute to the
 infrastructure documentation by making a pull request to the
 https://pagure.io/infra-docs/[infra-docs] repository. Access is via the
 bastion.fedoraproject.org machine and from there to each machine. See
-the xref:ssh.adoc[ssh-sop] for instructions on how to set up SSH. You can see a list
-of hosts that allow apprentice access by using:
+the xref:sshaccess.adoc[ssh-sop] for instructions on how to set up SSH.
+You can see a list of hosts that allow apprentice access by using:
 
 ....
 $  ./scripts/hosts_with_var_set -i inventory/ -o ipa_client_shell_groups=fi-apprentice