The user base of a package that uses transients can be very diverse. This is certainly the case for Magit; some users have been using it and Git for a decade, while others are just getting started now.
For that reason a mechanism is needed that authors can use to classify a transient’s infixes and suffixes along the essentials…everything spectrum. We use the term "levels" to describe that mechanism.
Each suffix command is placed on a level and each transient has a level (called transient-level), which controls which suffix commands are available. Integers between 1 and 7 (inclusive) are valid levels. For suffixes, 0 is also valid; it means that the suffix is not displayed at any level.
The levels of individual transients and/or their individual suffixes
can be changed interactively, by invoking the transient and then
C-x l to enter the "edit" mode, see below.
The default level for both transients and their suffixes is 4. The
transient-default-level option only controls the default for
transients. The default suffix level is always 4. The authors of
transients should place certain suffixes on a higher level, if they
expect that it won’t be of use to most users, and they should place
very important suffixes on a lower level, so that they remain
available even if the user lowers the transient level.
(Magit currently places nearly all suffixes on level 4 and lower levels are not used at all yet. So for the time being you should not set a lower default level and using a higher level might not give you as many additional suffixes as you hoped.)
This option controls which suffix levels are made available by default. It sets the transient-level for transients for which the user has not set that individually.
This file is used to persist the levels of transients and their suffixes between Emacs sessions.
This command enters edit mode. When edit mode is active, then all infixes and suffixes that are currently usable are displayed along with their levels. The colors of the levels indicate whether they are enabled or not. The level of the transient is also displayed along with some usage information.
In edit mode, pressing the key that would usually invoke a certain suffix instead prompts the user for the level that suffix should be placed on.
Help mode is available in edit mode.
To change the transient level press
C-x l again.
To exit edit mode press
Note that edit mode does not display any suffixes that are not
magit-rebase for example shows different suffixes
depending on whether a rebase is already in progress or not. The
predicates also apply in edit mode.
Therefore, to control which suffixes are available given a certain state, you have to make sure that that state is currently active.