Update update states docs

Signed-off-by: Mattia Verga <[email protected]>

docs/user/update_states.rst

@@ -6,18 +6,16 @@ Once submitted to Bodhi, updates move through the following states:
 
 :ref:`pending`: The update has not yet been pushed to the testing or stable repositories.
 
+:ref:`pending-testing`: The package is ready to go testing, and will wait until the next update push.
+
 :ref:`testing`: The package is in the updates-testing repository for people to test.
 
 :ref:`testing-stable`: The package is ready to go stable, and will wait until the next update push.
 
-:ref:`frozen`: The package is held back in the testing repository for additional checks.
-
 :ref:`stable`: The package has been released to the main updates repository.
 
 :ref:`obsolete`: The package has been obsoleted by a different update
 
-:ref:`revoked`: The update was removed before it reached the testing or stable repository.
-
 :ref:`unpushed`: The update has been removed from testing.
 
 .. note:: | In the case of Fedora rawhide, the states described here are a little bit changed
@@ -42,6 +40,15 @@ update must not break the upgrade path or it will be rejected.
 Bodhi will send e-mail notifications when the update has been signed and pushed.
 
 
+.. _pending-testing:
+
+Pending/Testing
+===============
+
+The update is ready to be pushed into the testing repositories, which will happen at the next
+compose run.
+
+
 .. _testing:
 
 Testing
@@ -50,36 +57,26 @@ Testing
 The testing status means that the update has been pushed to its release's testing repository. While
 in the testing repository users may provide feedback via karma and comments. Once enough feedback is
 generated, Bodhi's web interface can be used to release the update by clicking
-'Mark as Stable', or it can be removed by using 'Delete'. The command line interface can
+'Mark as Stable', or it can be removed by using 'Unpush'. The command line interface can
 also be used to perform these actions.
 
-If the update is configured to use the 'autopush', it will automatically be pushed or unpushed based
+If the update is configured to use the 'autokarma', it will automatically be pushed or unpushed based
 on the feedback from testers. This feature can be disabled if you wish to push your update to the
-stable repository manually. By default, if your update achieves a karma of 3, it will automatically
-be pushed to stable, and will be unpushed if it reaches -3.
+stable repository only manually. By default, if your update achieves a karma of 3, it will
+automatically be pushed to stable, and will be unpushed if it reaches -3.
 
-Testing also has two possible substates, both expressed as the "request", that occur when your
-package is ready to go to stable. These are documented in the next two sections.
+Also, the 'autotime' setting can be enabled, so that the update will be automatically pushed to stable
+after spending a certain amount of time in testing repositories, even if it has not reached a minimum
+karma. On the other hand, if any user submits negative karma, the 'autotime' feature will be disabled.
 
 
 .. _testing-stable:
 
 Testing/Stable
 ==============
 
-The "stable" state means that the package will be sent out to the stable
-repositories the next time a Release Engineer runs the update push command. The update will remain
-in the testing repository during this state.
-
-
-.. _frozen:
-
-Frozen
-======
-
-A package is said to be in a frozen state when a release is stabilized before the release Beta or
-GA (Generaly Available). In such a state, all updates are blocked and release engineering will only
-push the updates that have been given a freeze break exception to fix a bug.
+The update is ready to be pushed into the stable repositories, which will happen at the next
+compose run. The update will remain in the testing repository during this state.
 
 
 .. _stable:
@@ -102,20 +99,33 @@ updates that do not have an active push request. Once obsoleted, the new update
 update's bugs and notes.
 
 
-.. _revoked:
-
-Revoked
-=======
-
-If the update is in pending request for testing, then revoking it will put the update in the
-`unpushed`_ status. If the update is in testing request stable, then revoking will keep the
-`testing`_ status.
-
-
 .. _unpushed:
 
 Unpushed
 ========
 
 The developer has decided to pull the update from the testing repository. This state can only be
 reached if the update is in the testing state.
+
+
+Revoking push requests
+======================
+
+When an update is moving from pending to testing or from testing to stable, the developer can revoke
+the push request either from the webUI or from CLI with the 'revoke' command.
+
+Revoking a testing request will set the update to the Unpushed state. The developer can then
+re-submit the update to testing and restart the update flow.
+
+Revoking a stable request will cause the update to remain in the testing repositories and not be
+pushed to stable at the next compose. Be aware if any of 'autokarma' or 'autotime' are enabled,
+the update will automatically be resubmitted to stable after a short amount of time. To prevent that
+the developer has to edit the update and disable those automatisms.
+
+
+Frozen updates
+==============
+
+A package is said to be in a frozen state when a release is stabilized before the release Beta or
+GA (Generaly Available). In such a state, all updates are blocked and release engineering will only
+push the updates that have been given a freeze break exception to fix a bug.