Package: devpi-pr
devpi-pr: pull request plugin for devpiThis plugin adds apull requestworkflow todevpi-serverand supporting commands todevpi-client.Installationdevpi-prneeds to be installed alongsidedevpi-serverto enablepull requestfunctionality.On client machines the creation and submission ofpull requestsis possible without the plugin, but more convenient with it installed.
All other functionality requires thedevpi-prplugin to be installed alongsidedevpi-client.You can install it with:pip install devpi-prThere is no configuration needed asdevpi-serveranddevpi-clientwill automatically discover the plugin through calling hooks using the setuptools entry points mechanism.MotivationMany Python projects have complex dependencies and are often split into separate packages.For such projects it would be advantageous to handle a set of packages as a single unit.In organizations an authenticated flow of package releases is often required.This plugin introduces the concept of apull requestto help with all that.The result of a successfulpull requestis a single atomic update of packages in the target index.UsageThedevpi-prplugin adds new commands when installed alongsidedevpi-client.new-prCreate a new pull request.submit-prSubmit an existing pull request for review.list-prsList pull requests.review-prStart reviewing a submitted pull request.abort-pr-reviewAbort review of pull request.approve-prApprove reviewed pull request.reject-prReject pull request.cancel-prCancelsubmittedstate of pull request by submitter.delete-prCompletely remove a pull request including any uploaded packages.Indevpi-serverapull requestis represented by a specialpr index.
It behaves mostly like a regular index with some additional restrictions and behaviors.All commands which change the state of apull requestask for a message and accept the-moption to provide it directly.
When theEDITORenvironment variable is set it is used to open an editor to provide a message,
otherwise a simple prompt is used.Creating a pull requestLets say a new feature is created which requires changes in multiple packages.
We are currently working on a development indexuser/devwhere we have two changed packagespkg-app1.0andapp-dependency1.2.
The target index where the packages should end up for production is namedprod/main.Thepull_requests_allowedoption of the target index must beTrue:$devpiindexprod/mainhttp://example.com/prod/main:type=stagebases=root/pypivolatile=Trueacl_upload=rootacl_toxresult_upload=:ANONYMOUS:mirror_whitelist=pull_requests_allowed=TrueWe first create a newpull requestfor the target:$devpinew-prnew-featureprod/mainThis creates a newpr indexnameduser/new-feature.Next we push the existing packages from our development index into thepr index.$devpipushpkg-app==1.0user/new-feature$devpipushapp-dependency==1.2user/new-featureAs thepr indexis mostly like a regular index,
it is also possible to upload new packages directly to thepr indexwithdevpi uploador standard tools liketwine.For convenience it is also possible to list multiple packages upon first creation to let them automatically be copied:$devpinew-prnew-featureprod/mainpkg-app==1.0app-dependency==1.2If only the package name is given,
then the latest version is used.Afterwards thepull requestcan be submitted for review:$devpisubmit-prnew-featureThis will ask for a message.The state of thepr indexis now set topending.Reviewing a pull requestAny user with write access to the target index (seeacl_uploadoption of indexes in devpi-server) can now review thepull request.To see currentpull requestsfor an index use thelist-prscommand:$devpilist-prsprod/mainpendingpullrequestsuser/new-feature->prod/mainatserial123A review is started with thereview-prcommand:$devpireview-prnew-featureAt this point thepr indexcan be used to install the new packages withpipetc just as a regular index.Once the review is complete it can be accepted:$devpiaccept-prnew-featureThis again requires a message like for thesubmit-prcommand.When thepull requestis accepted the latest contained version of all packages is copied to the target index in one atomic step.
Afterwards thepr indexis automatically deleted.If there have been any changes on the index after thereview-prcommand,
then theaccept-prcommand will fail.
To continue another call ofreview-prwith the-uoption is required:$devpireview-pr-unew-featureThis prevents unexpected changes to be accepted.
After reviewing the changes thepull requestcan be accepted again.In case thepull requestneeds further work,
it can be rejected with thereject-prcommand and a message:$devpireject-prnew-feature-m"See comments in ticket #42 about a bug I found."Manual creation of pr indexIt’s also possible to create apull requestmanually.
This works withoutdevpi-prinstalled alongsidedevpi-client,
but is more complex.First a newpr indexneeds to be created.
The index must be of typepr, the target index specified inbasesandstatesandmessagesbe set:$devpiindex-cnew-featuretype=prbases=prod/mainstates=newmessages="New pull request"Once the index is created, packages can be uploaded to it withdevpi uploador pushed from another index withdevpi push.At last the state of the index needs to be updated topendingand a state change message be added:$devpiindexnew-featurestates+=pendingmessages+="Please approve these updated packages"Changelog1.0.0 - 2019-10-31Initial release.
[fschulze (Florian Schulze)]