Skip to content

Staging Workflow

Jump to bottom
Saray Cabrera Padrón edited this page Oct 22, 2019 · 33 revisions

#Workflows

Description and diagram

##Using Staging Workflow

###Setup a Staging Workflow

Anyone can setup a Staging Workflow in their own project. There are to ways to do it: using the web Interface or the osc tool.

If you use the web interface, you just need to go to the Staging tab in the project page, assign the "Managers Group" which will be the owner of that Staging Workflow and click on "Create Staging Projects". Only the owner of the project and the users of the chosen Managers Group can manage the Staging Workflow.

To do the same thing using the osc tool, you only have to run the next command, specifing the group that will manage the Staging Workflow:

  • osc api -X POST '/staging/openSUSE:Leap:15.2/workflow' -d '' ###Post Setup

Once the Staging Workflow is created successfully, two empty Staging Projects will be ready for you. Following the example, if the project name is 'openSUSE:Leap:15.2', they'll be named after it like 'openSUSE:Leap:15.2:A' and 'openSUSE:Leap:15.2:B'. The purpose of those projects is to work as a playground area to test several packages together. Of course you can create as many extra Staging Projects as you need or assign an existing Staging Project to a Staging Workflow where you have rights (e.g: a subproject).

###Using a Staging Project as a Template

As any other project, the staging project could have a specific configuration (repositories, users and groups, etc) therefore, sometimes it can be useful to copy an existing staging project (template), instead of creating one from scratch. For example, if we use 'openSUSE::Leap:15.2:Staging:A' as template, the new staging project will contain the same configuration, repositories, users and groups than the original one.

  • osc api -X POST '/staging/openSUSE:Leap:15.2/staging_projects/openSUSE:Leap:15.2:Staging:A/copy/openSUSE:Leap:15.2:Staging:A_copy' ###underlineStaging Workflow Usage / Playing around with a Staging Projectunderline

With the initial setup done, we can start using the Staging Workflow.

###Branch a package

Create a branch from a package you intend to contribute to. Go to the package and click on the "Branch Package" button. Now you can add the changes you need to the files of the branched package.

###Create a request for the package

After modifying the branched package, is time to submit a Request to ask for a review on the changes.

A request in 'review' state is created and shown in the Backlog section of the Staging Workflow page. That Request will have a Review for the managers group, what we call a Review by_group.

At this point, the Staging Project is in 'acceptable' state.

###Stage Request into Staging Project

The main purpose of the Staging Workflow is to provide a way to stage a bunch of packages and ensure that they work well together. To stage the requests together we have to use the osc tool:

  • osc api -X POST '/staging/openSUSE:Leap:15.2/staging_projects/openSUSE:Leap:15.2:Staging:A/staged_requests' -d '705329705365' After this we could check if it was correctly staged with the following command, that will show to us all the requests that are staged in a staging project.

  • osc api '/staging/openSUSE:Leap:15.2/staging_projects/openSUSE:Leap:15.2:Staging:A/staged_requests'

Once the Request is assigned, it gets another Review against the staging project provided before. This review its a Review by_project. The Request disappears from the Backlog and is shown next to the Staging Project name in the table.

###Unstage Request

When testing some packages together in a Staging Project, we might get conflicts or realize that any of them is no longer valid. In such cases, we can unstage a Request and test the Staging Project again with the rest of the packages.

The unstaged requests will be sent back to the Backlog.

  • osc api -X DELETE '/staging/openSUSE:Leap:15.2/staged_requests' -d '705365' ###Move Staged Requests between Staging Projects

Unfortunately, at the moment moving staged request between Staging Projects is not possible, the only way is unstaging the request and staging it into a different Staging Project.

###Exclude Requests

Sometimes it can be useful to exclude a request and don't let it be available in the Backlog. This can prevent the staging project from being assigned with requests we are sure are causing conflicts, have some missing dependencies or have to wait for other request to be accepted. It is always important to describe the reason to exclude a request.

Of course to exclude a request you need to provide a reason.

We can exclude requests via the Web UI one by one, going to the Staging Overview page, clicking on the Excluded link in the Infos section, then clicking on the "Exclude requests" link at the bottom of the page.

We can do it also via the osc tool, and we can exclude several requests at once:

  • osc api -X POST '/staging/openSUSE:Leap:15.2/excluded_requests' -d "<excluded_requests></excluded_requests>" If we stop having reasons to exclude a request, we can remove the exclusion and the request will return to the Backlog, ready to be staged into a Staging Project.

  • osc api -X DELETE '/staging/openSUSE:Leap:15.2/excluded_requests' -d "<excluded_requests>670595</excluded_requests>' ###Merge staging project

Once all requests are ready and the staging project has an acceptable state, we can merge (accept) the Staging Project. In other words, all the requested changes we tested in the Staging Project can now be integrated into the main project, in this case openSUSE:Leap:15.2.

To accept/merge the staging project we have to use the following command from osc:

  • osc api -X POST '/staging/openSUSE:Leap:15.2/staging_projects/openSUSE:Leap:15.2:Staging:A/accept'

###Required Checks

Given a Staging Workflow project we can define several Required Checks and associate them to:

- Requests: to check sources.
- Repository or Repository+Architecture: to check binaries.

Once they are built and published. When the checks finish, they will report back to OBS with the check result, and the final status of the checks will be available here:

\url{http://example.com/staging\_workflows/3/staging\_projects/openSUSE:Leap:15.2:Staging:A}

How the tools start checking whatever they have to check, is up to the tool to decide. We only recommend to channel all communication with OBS via the message bus.

If all the required checks succeed the Staging Project can be accepted, and they will be merged onto the main project. Otherwise, they should be reviewed to have the staging project in an acceptable state.

\url{https://build.opensuse.org/apidocs/index#177}

##References

The official documention

OBS documentation

Basic relationships

  • A Project has one StagingWorkflow
  • A StagingWorkflow has many StagingProjects
  • A StagingProject has many StageRequests
  • A StagedRequest has one BsRequest
  • A BsRequest has many Reviews

StagingWorkflow

What is the meaning of "Backlog"?

Requests with open review by group that are not staged or excluded.

What does it mean that a BsRequest has a Review.by_group for a StagingWorkflow.managers_group?

To tell people that the request is going to be staged, and to prevent this request to be merged into the main project.

What is the meaning of "Excluded"?

Requests that the manager doesn't want to include in a stage. The belong to the model Staging::RequestExclusion.

StagingProject

What makes a project acceptable?

The overall_state method defines whether a StagingProject can be accepted or not. The following conditions should be met to make a StagingProject acceptable:

  • if it is not empty
  • if there are no untracked requests or obsolete requests (requests in state 'declined', 'superseded' or 'revoked')
  • if there are no unfinished builds for any StagedRequest of a StagingProject
  • if there are no open reviews for any StagedRequest of a StagingProject
  • if there are no open StatusChecks for any Repositories of a StagingProject

How to accept the project?

Accepting a StagingProject means to accept all requests that are staged for this project. Once the requests have been accepted, they are unstaged from the project. While a StagingProject is being accepted it is in state 'accepting'. Once this is done it's state is 'empty'.

@staging_project.staged_requests.each do |staged_request|
   staged_request.request.reviews.accept # the by project review
   staged_request.request.accept....
   staged_request.destroy # Remove the relationship
end

StageRequest

StagedRequest, is a request which is assigned to a specific StagingProject

What is the meaning of "Ready"?

StageRequest is ready if it doesn't have any open reviews.¹ A StateRequest cannot be excluded once it's "ready".

¹ The review by project on the StagingProject is ignored. See the question below.

What does it mean that a BsRequest has a Review.by_project for a StagingProject?

This prevents users from merging BsRequests that are staged in a StagingProject and visualizes which StagingProject the request is staged to. Be aware that technically it would still be possible to accept such a BsRequest.

What is the meaning of "In review"?

StageRequest is "In review" if it has at least one open review.¹

What is the meaning of "Obsolete"?

StageRequest is "Obsolete" because it is in the state: declined, superseded or revoked.

What is the meaning of "Delete"?

Shows if the BsRequest has a BsRequestActionDelete action for deleting a package

General questions

Why is there a problems lane for StagingProjects on the StagingWorkflow show page?

The idea is to show if there is any build problems, or status checks, blocking the acceptance of the StagingProject.

What does the percentage (in each state of a staging project) mean?

It shows the progress of the current state, for example 2 requests with 7 open reviews and 3 closed ones would have a review progress of 70%.

Staging Workflow HowTo

Learn how to use it, with this step by step guide.

Development

Subsystems

Better SCM/CI Integration

HOWTOs

Software Design Patterns

Operations

Releases

Clone this wiki locally