Clean up docs: remove outdated pages, migrate some content to newer ones

docs/conf.py

@@ -87,16 +87,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.0'
+version = '2026'
 # The full version, including alpha/beta/rc tags.
-release = '3.0'
+release = '2026'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -316,18 +316,10 @@
 #texinfo_no_detailmenu = False
 
 linkcheck_ignore = [
-    # These links require you to be behind the VPN.
-    'http://sentry.mktmon.services.phx1.mozilla*',
-    'http://dashboard.mktadm.ops.services.phx1.mozilla.com*',
-    'https://mana.mozilla.org*',
-    # For some unknown reason, TravisCI gets a 404 for calendar URLs.
-    # They require a login so maybe that's why.
+    # Calendar URLs require a login.
     'https://calendar.google.com/calendar/embed*',
-    # This is a private URL.
-    'https://github.com/mozilla/addons-server-security',
     # TravisCI doesn't like CircleCI (or otherwise) so we get a 404
     'https://circleci.com/gh/mozilla*',
-    'https://app.datadoghq.com/*',
     # Ignore this as the fragment id is non-existent.
     'https://chat.mozilla.org/#/room/#amo:mozilla.org',
     # Ignore about: pages

docs/index.rst

@@ -16,14 +16,13 @@ Contents:
    repositories.rst
    browser/index.rst
    l10n.rst
-   server/index.rst
+   push_duty/index.md
    ux/index.rst
    random/index.rst
 
 Filing bugs:
 
-* Github on `this repository <https://github.com/mozilla/addons/issues>`_.
-* Bugzilla
+* See [repositories](./repositories.rst)
 
 Indices and tables
 ==================

docs/push_duty/extension-workshop.md

@@ -0,0 +1,6 @@
+# Deploying extension-workshop
+
+extension-workshop is deployed separately by folks who update its contents
+without the involvement of the push hero.
+
+See [https://github.com/mozilla/extension-workshop#deploymentsreleases](https://github.com/mozilla/extension-workshop#deploymentsreleases)

docs/push_duty/index.md

@@ -0,0 +1,48 @@
+# Push Duty
+
+Production deploys are scheduled every other week. Push duty rotates each deploy to another developer. The current rotation is:
+
+- eviljeff
+- mat
+
+## Before the push
+
+Before a push, we continuously land and deploy code to dev by merging PRs to master in respective repositories. During this time, individuals and/or the push hero might update the upcoming release document with notes for pre/post deployment tasks. Refer to the [release docs](./release-docs) for more information.
+
+On Tuesday around [09:00 PT](http://www.timebie.com/std/pst.php?q=9), we deploy to stage. This is the time to publish the release that will be deployed to stage (see [release docs](./release-docs)).
+
+QA will then check stage for defects.
+
+### Cherry-picks
+
+If any follow-ups are needed after the release has been deployed to stage, (see [cherry picking](./cherry-picking)).
+
+## During Push
+
+On Thursday around [09:00 PT](http://www.timebie.com/std/pst.php?q=9), we deploy to production. This is the time to:
+
+- Meet with QA in the `#addons-production` slack channel
+- Approve the stage deployments to push to production
+- Push extension-workshop to production if needed (see [tag-services](./tag-services))
+- Monitor the push in sentry and grafana for any issues (see [monitoring](./monitoring))
+
+## After the push
+
+- Create a new release document for the next push hero (see [release docs](./release-docs))
+- Update the topic of the `#addons-production` slack channel to include the handle of next week's push hero
+
+## Runbooks
+
+This section will outline the steps to take for specific actions that you might need to perform before, during and/or after a push. The push runbook is a living document and should be updated as needed. Please reference it in the push notes for each push. As well as in the above push duty document.
+
+```{toctree}
+:maxdepth: 2
+
+release-docs.md
+tag-services.md
+cherry-picking.md
+monitoring.md
+project-dependencies.md
+security-fixes.md
+extension-workshop.md
+```

docs/push_duty/monitoring.md

@@ -0,0 +1,15 @@
+# Monitoring
+
+QA will perform a sanity check on the site once the push is done.
+
+The best places to monitor the results of the push are:
+
+  * `Sentry <https://sentry.prod.mozaws.net/operations/olympia-prod/>`_
+  * `Grafana <https://https://yardstick.mozilla.org/>`_
+  * `SRE dashboard <https://yardstick.mozilla.org/d/CsSDyxTZ1/amo?>`_
+  * `Prod Health dashboard <https://yardstick.mozilla.org/d/3q-fOyOWk34/amo-prod-health>`_
+  * `API usage/performance dashboard <https://yardstick.mozilla.org/d/kiTC7XDZ1/amo-prod-frontend-apis-usage-performance>`_
+
+The site performance graphs should show no large spikes or changes.
+Sentry should show no new errors, although it will show intermittent errors and the occasional
+error as the push occurs.

docs/push_duty/project-dependencies.md

@@ -0,0 +1,15 @@
+# Project dependencies
+
+Project dependencies are not tagged as part of the push duty responsibilities.
+If you're working on a feature in a project that's a dependency of a project
+e.g. ``addons-linter``, then it's *your* responsibility to make a release and
+update the project that consumes that dependency in time for the tag.
+
+This way we can ensure that:
+
+  * Dependency packages are built and released in time for the tag.
+  * The new feature in the new version of a package has been validated on
+    -dev.
+
+Making multiple releases of a package during a weekly milestone is totally
+fine since this helps with testing smaller sets of changes.

docs/server/push_duty/release-docs.md → docs/push_duty/release-docs.md

@@ -1,4 +1,4 @@
-# release-docs
+# Releasing AMO
 
 Until August 22nd 2024, we managed our release documents manually in the addons repository (see [release-docs.rst][addons-releases]).
 
@@ -8,32 +8,36 @@ Currently, [addons-server][addons-server] is the only repository deploying via [
 
 To create a new release, use the [draft release workflow][draft-release-workflow].
 
-<img src="../../images/draft_release.png" width="50%">
+<img src="../images/draft_release.png" width="50%">
 
 This will create a new draft release in the repository. This release can be updated with instructions and things to note for the next push.
-You need to set the push hero (see [push-duty](./index.md) for the rotation) as the assignee for the draft release.
-You also need to specify the next push date. This will be roughly 2 weeks after the current push. The exact date will correspond
-with the next jira sprint.
+You need to set the push hero (see [push-duty](./index.md) for the rotation) as the assignee for the draft release. and the next push date, in `YYYY.MM.DD` format. This should be 2 weeks after the current push, the exact date will correspond with the next jira sprint.
 
-## Publishing a release
+## Deploying to stage
 
-During the tag, we can trigger a staging deployment for `addons-server` by publishing the current draft release
-that should have been created at the end of the last push. It will likely be the first release in the [list][addons-server-releases]
-and will match the current push tag date.
+During the release process, we can trigger a staging deployment for `addons-server` by publishing the current draft release that should have been created at the end of the last push. It will likely be the first release in the [list][addons-server-releases] and will match the current push tag date.
+
+### Handling addons-frontend
+
+addons-frontend is currently not using GitHub Actions, so manual tagging is required. See [tag-services][./tag-services.md]. Once the tag has been pushed, CI will run and eventually a new docker image should be built and deployed to stage.
+
+You can then go back to addons-server draft release to update the compare link to the previous tag for addons-frontend.
+
+### Publishing a release
 
 In order to publish the release, click the edit icon at the top right of the release card.
 
 - Update the release notes by clicking the `Generate release notes` button.
 - Publish the release by clicking the `Publish release` button.
 - Include the compare link for `addons-frontend`. See [tagging](./tag-services.md) for details.
 
-<img src="../../images/publish_release.png" width="50%">
+<img src="../images/publish_release.png" width="50%">
 
 ```{warning}
 Make sure that the release is tagged as "latest". This is the default behavior but don't accidentally un-check it.
 ```
 
-<img src="../../images/latest_release.png" width="50%">
+<img src="../images/latest_release.png" width="50%">
 
 Publishing a release will trigger the [release workflow][release-workflow].
 
@@ -52,9 +56,14 @@ to see workflows triggered by a release event that failed.
 We should include slack notifications for failed CI, especially on deployment triggering workflow runs.
 ```
 
+## Deploying to production
+
+Follow [documentation in Confluence about how to deploy with ArgoCD][deploy-argo-cd].
+
 [failed-ci-query]: https://github.com/mozilla/addons-server/actions/workflows/ci.yml?query=event%3Arelease+is%3Afailure
 [release-workflow]: https://github.com/mozilla/addons-server/actions/workflows/release.yml
 [draft-release-workflow]: https://github.com/mozilla/addons-server/actions/workflows/draft_release.yml
 [addons-server]: https://github.com/mozilla/addons-server
 [addons-server-releases]: https://github.com/mozilla/addons-server/releases
 [addons-releases]: https://github.com/mozilla/addons/tree/main/releases
+[deploy-argo-cd]: https://mozilla-hub.atlassian.net/wiki/spaces/SRE/pages/27921597/AMO+Dev+Resources#ArgoCD

docs/push_duty/security-fixes.md

@@ -0,0 +1,14 @@
+# Security fixes
+
+Security issues against AMO are currently reported in Bugzilla. When someone is
+assigned to work on one, they should open a new draft security advisory
+describing the security issue and linking to the bugzilla bug, but not publish
+it. That unlocks the ability to have a private PR and fork to work on the
+issue.
+
+The corresponding private PR should is reviewed as normal but once it has been
+reviewed, it should *not* be merged right away. Instead, it should be called
+out in the release notes for the next release. Merging to ``master`` is part
+of push duty and happens right before tagging, using GitHub regular merge
+functionality on the PR. The advisory can then be closed (it's never
+published).

docs/repositories.rst

@@ -17,31 +17,31 @@ An API for building add-ons that works with e10s and is compatible with Google C
 GitHub
 ------
 
-Almost everything else is on GitHub and issues are tracked in GitHub. This is a non-exhaustive list. Other repositories and libraries do appear around these main libraries:
+Almost everything else is on GitHub and issues are tracked in GitHub. This is a non-exhaustive list. Other repositories and libraries do appear around these main repositories:
 
 addons
 ~~~~~~
 `These docs <https://mozilla.github.io/addons/>`__ and an issue tracker. `This repository <https://github.com/mozilla/addons>`__ serves as an umbrella for everything add-ons.
-Bug tracker is in GitHub and can be used for almost anything add-ons related. `Existing bugs <https://github.com/mozilla/addons/issues/>`__.
+Bug tracker is in GitHub and can be used for almost anything add-ons related. `Existing issues <https://github.com/mozilla/addons/issues/>`__.
+
+addons-frontend
+~~~~~~~~~~~~~~~~~~~
+The `addons.mozilla.org <https://addons.mozilla.org/>`__ website. The `repository <https://github.com/mozilla/addons-frontend>`__ is on GitHub.
 
 addons-server
 ~~~~~~~~~~~~~
-The `addons.mozilla.org <https://addons.mozilla.org/>`__ website. The `repository <https://github.com/mozilla/addons-server>`__ and `issue tracker <https://github.com/mozilla/addons-server/issues/>`__ is on GitHub. Documentation is `on github pages <https://mozilla.github.io/addons/>`__.
+Complement to addons-frontend, this contains API, Developer Hub, Reviewer Tools and Admin Tools for AMO. The `repository <https://github.com/mozilla/addons-server>`__ is on GitHub. Documentation is `on GitHub pages <https://mozilla.github.io/addons/>`__.
 
 In the past this repository has been known as *remora*, *zamboni* or *olympia*.
 
-addons-code-manager
-~~~~~~~~~~~~~~~~~~~
-A web application to manage add-on source code, such as reviewing code for add-ons submitted to addons.mozilla.org. The `repository <https://github.com/mozilla/addons-code-manager>`__ and `issue tracker <https://github.com/mozilla/addons-code-manager/issues/>`__ is on GitHub.
+addons-blog
+~~~~~~~~~~~
+Static content generator for AMO's blog, `addons.mozilla.org/blog <https://addons.mozilla.org/blog/>`__.
 
 addons-linter
 ~~~~~~~~~~~~~
 The linter checks WebExtensions for common errors and potential problems. It is used on `addons.mozilla.org <https://addons.mozilla.org/>`__ and `web-ext <https://github.com/mozilla/web-ext/>`__. It can also be run in stand-alone mode. The `repository <https://github.com/mozilla/addons-linter>`__, `issue tracker <https://github.com/mozilla/addons-linter/issues/>`__ and `documentation <https://mozilla.github.io/addons-linter/>`__ is on GitHub.
 
-dispensary
-~~~~~~~~~~
-The dispensary collects and offers hashes of popular JavaScript libraries, mainly for the Mozilla's `addons-linter <https://github.com/mozilla/addons-linter>`__. The `repository <https://github.com/mozilla/dispensary>`__ and `issue tracker <https://github.com/mozilla/dispensary/issues/>`__ is on GitHub.
-
 web-ext
 ~~~~~~~
 This is a command line tool to help build, run, and test `WebExtensions <https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions>`__. The `repository <https://github.com/mozilla/web-ext>`__ and `issue tracker <https://github.com/mozilla/web-ext/issues/>`__ is on GitHub. The `documentation <https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/>`__ and `command reference <https://extensionworkshop.com/documentation/develop/web-ext-command-reference>`__ is on Extension Workshop.