Add Staging plugin documentation.
This commit is contained in:
parent
547f2d39c6
commit
4631989bdb
216
docs/staging.asciidoc
Normal file
216
docs/staging.asciidoc
Normal file
@ -0,0 +1,216 @@
|
||||
Staging Plugin Documentation
|
||||
============================
|
||||
:author: openSUSE Team at SUSE
|
||||
:toc:
|
||||
|
||||
|
||||
Introduction
|
||||
------------
|
||||
[id="intro"]
|
||||
|
||||
The staging plugin is used to enable the new
|
||||
https://progress.opensuse.org/workflow/factory-proposal.html[factory
|
||||
workflow] to work with staging projects. This plugin implement some
|
||||
functionality that some day will be directly implemented in OBS
|
||||
itself. Meanwhile this plugin is used as a playground field to
|
||||
explore these new concepts and operations.
|
||||
|
||||
This plugin is used by the release manager to move requests into
|
||||
staging projects to evaluate the behavior and inter-compatibility of
|
||||
different changes working together.
|
||||
|
||||
An staging project is a mere project linked to Factory, but with some
|
||||
packages that are different as a result of one or several requests.
|
||||
When the release manager assign a request into a staging project, this
|
||||
request is review inside this project.
|
||||
|
||||
TODO: Describe the permissions that are needed in OBS to operate with
|
||||
the plugin.
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
[id="install"]
|
||||
|
||||
Clone this repository:
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
git clone https://github.com/openSUSE/osc-plugin-factory.git
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
Link +osc-staging.py+ and the library either to +~/.osc-plugins+ or
|
||||
+/var/lib/osc-plugins+
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
cd osc-plugin-factory
|
||||
ln -sr ./osc-staging.py ./osclib ~/.osc-plugins
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
|
||||
Command line
|
||||
------------
|
||||
[id="cli"]
|
||||
|
||||
This plugin is expected to be used interactively. The basic commands
|
||||
are:
|
||||
|
||||
* *accept* Accept all requests assigned to a staging project.
|
||||
|
||||
* *check* Check the status of the different request inside the staging
|
||||
project, including the status in openQA.
|
||||
|
||||
* *cleanup_rings* Check the status of the different rings in Factory.
|
||||
|
||||
* *freeze* Freeze the packages that are not affected in a staging project.
|
||||
|
||||
* *list* Accept all the requests from packages that are not in any
|
||||
ring, detect request that supersede the current ones that are
|
||||
actually tracked in staging projects, and list the remaining
|
||||
requests.
|
||||
|
||||
* *select* Move a request (or a list of requests) to a staging
|
||||
project, or move requests between staging projects.
|
||||
|
||||
* *unselect* Remove a request from a staging project, and publish it
|
||||
again into the backlog.
|
||||
|
||||
|
||||
List
|
||||
~~~~
|
||||
|
||||
This action will list all the requests that are candidates to be
|
||||
assigned to a different staging project. To decide this list, this
|
||||
command will perform to actions with side effects into the requests
|
||||
status.
|
||||
|
||||
The first action is to accept requests that do not affect packages
|
||||
that are not inside one of the rings that are defined in Factory.
|
||||
This acceptance will move the request to the next status of revision
|
||||
(maybe waiting to the manual review or the legal review)
|
||||
|
||||
The second action is to detect if a request supersede a different one
|
||||
that is currently in a staging project. If this is the case, this
|
||||
command will replace the old request by the new one, declining the
|
||||
superseded after this.
|
||||
|
||||
Because of the different side effects, this command needs to be
|
||||
executed with the proper permissions in OBS.
|
||||
|
||||
|
||||
Select
|
||||
~~~~~~
|
||||
|
||||
The release manager or the staging project manager can take a request
|
||||
and assign it into a staging project using the +select+ command.
|
||||
|
||||
Actually we have
|
||||
https://build.opensuse.org/project/subprojects/openSUSE:Factory:Staging[ten
|
||||
staging projects], that are managed according to some internal rules.
|
||||
Every time that the manager decides to move a request to one of those
|
||||
projects, a metadata attached to these projects are updated, and a new
|
||||
commend is generated.
|
||||
|
||||
The metadata associated to a staging project contain the list of
|
||||
request that are assigned to this project, and is used by the plugin
|
||||
to track and manage the different requests. For example, the command:
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
osc staging select A 12345
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
will add the request #12345 into the staging project
|
||||
openSUSE:Factory:Staging:A. This command will take care that this
|
||||
request was not previously in the staging project A or in a different
|
||||
one. If this is the case, will show an error message and exit without
|
||||
selecting the request. Is we want to move a request from one staging
|
||||
project to another one, we need to use the parameter +--move+:
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
osc staging select --move B 12345
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
This command will move #12345 from openSUSE:Factory:Staging:A to
|
||||
openSUSE:Factory:Staging:B
|
||||
|
||||
|
||||
Unselect
|
||||
~~~~~~~~
|
||||
|
||||
The +unselect+ command will untrack a request from a staging project,
|
||||
returning it back to the original backlog (without approving or
|
||||
declining the request) So for example, if #12345 is being tracked in
|
||||
A, the command:
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
osc staging unselect 12345
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
will find the correct staging project and remove the request from it.
|
||||
|
||||
|
||||
Check
|
||||
~~~~~
|
||||
|
||||
Before accepting the requests inside a staging project, the user can
|
||||
check the state of those requests. The +check+ command will check the
|
||||
project status, taking care of superseded requests or already accepted
|
||||
requests.
|
||||
|
||||
This command will also check the status in openQA of the project.
|
||||
|
||||
|
||||
Accept
|
||||
~~~~~~
|
||||
|
||||
If the current status of the staging project is good, this command
|
||||
will change the review status of the different requests assigned to
|
||||
the project, accepting them.
|
||||
|
||||
Internally, the +accept+ command contains a call to the +check+
|
||||
command to make sure that the request can be accepted.
|
||||
|
||||
After this command, the staging project status will be disabled, to
|
||||
avoid the overload of OBS.
|
||||
|
||||
|
||||
Cleanup Rings
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
https://build.opensuse.org/project/subprojects/openSUSE:Factory:Rings[Rings]
|
||||
are collection of packages that are deeply interconnected, and that
|
||||
are building basis for a different ring or for the rest of the
|
||||
distribution. A ring is a way to organize Factory into
|
||||
inter-dependent packages that are again used to build a different
|
||||
layer of Factory itself.
|
||||
|
||||
Actually we have identified three rings:
|
||||
|
||||
* https://build.opensuse.org/project/show/openSUSE:Factory:Rings:0-Bootstrap[openSUSE:Factory:Rings:0-Bootstrap]
|
||||
* https://build.opensuse.org/project/show/openSUSE:Factory:Rings:1-MinimalX[openSUSE:Factory:Rings:1-MinimalX]
|
||||
* https://build.opensuse.org/project/show/openSUSE:Factory:Rings:2-TestDVD[openSUSE:Factory:Rings:2-TestDVD]
|
||||
|
||||
And you can find a better description in the
|
||||
https://www.youtube.com/watch?v=K-wTVGqKFR8[talk conference]
|
||||
celebrated in 2014 in Dubrovnik, Croatia.
|
||||
|
||||
This command is used to check the current status of the rings and to
|
||||
find undesirable dependencies of the packages that conform the rings.
|
||||
|
||||
|
||||
Freeze
|
||||
~~~~~~
|
||||
|
||||
Factory is always a moving target, even with the staging projects. If
|
||||
we want to check the status of the request assigned to a staging
|
||||
project, sometimes is desirable to have a frozen status of the source
|
||||
packages that are part of Factory but not of the staging project.
|
||||
|
||||
This command is used to build frozenlink-kind-of links for a staging
|
||||
project.
|
||||
|
||||
|
||||
Use cases
|
||||
---------
|
||||
[id="usecases"]
|
||||
|
||||
XXX TODO
|
||||
Loading…
x
Reference in New Issue
Block a user