Patch Workflow

This is a very draft docs that aims to have a defined workflow for sending and applying patch.

It provides a background both for alpine developers and contributors.

It's in the form of FAQ, but it might be changed with a better approach.

Also, a graphical workflow would be useful. A nice idea is here: [1]

I want to contribute to Alpine project by sending patches. How can i do this?

First of all, thanks :)

Please, take a look at Development_using_git and docs linked to it.

How should i submit a patch to alpine-aports ML?

You can follow this document: Creating_patches

Please note that Patchwork is able to catch the patch if they are sent inline, rather than as attachment.

Ok, now i've an aports git tree ready and i've sent a patch to alpine-aports ML. And now?

Well done. Now the patch is in our workflow.

After you've sent the patch, it is going to be injected in patchwork.alpinelinux.org.

There's a web interface where you can see all the patches sent to git.

From there, alpine delevopers will check the patch and proceed accordingly.

Workflow status are:

New:

   Patch has been submitted to the list, and none of the maintainers has changed it's state since. Under Review:: 

Accepted:

   When a patch has been applied to a custodian repository that gets used for pulling from into upstream, they are put into "accepted" state. 

Rejected:

   Rejected means we just don't want to do what the patch does. 

RFC:

   The patch is not intended to be applied to any of the mainline repositories, but merely for discussing or testing some idea or new feature. 

Not Applicable:

   The patch does not apply cleanly against the current U-Boot repository, most probably because it was made against a much older version of U-Boot, or because the submitter's mailer mangled it (for example by converting TABs into SPACEs, or by breaking long lines). 

Changes Requested:

   The patch looks mostly OK, but requires some rework before it will be accepted for mainline. Awaiting Upstream:: 

Superseeded:

   Patches are marked as 'superseeded' when the poster submits a new version of these patches. 

Deferred:

   Deferred usually means the patch depends on something else that isn't upstream, such as patches that only apply against some specific other repository. 

Archived:

   Archiving puts the patch away somewhere where it doesn't appear in the normal pages and needs extra effort to get to. 

We also can put patches in a "bundle". I don't know yet if that has any deeper sense but to mark them to be handled together, like a patch series that logically belongs together.

Note: Set "approved" on webif does not have an impact on the git tree. If is actually approved, after pwclient git-am the state of the patch will automatically be changed to "approved". This is the right way to change state. Generally speaking, change the state on webif is not needed. Webpage only report what the user does with pwclient tool.

I'm an alpine developer. How can I start to use patchwork ?

There are two ways to work with patches from alpine-aports Mailing List:

.1 Web Interface: https://patchwork.alpinelinux.org/^{[Dead Link]}

.2 On your local build environment, you need pwclient:

   apk add pwclient 
   cd $your_aports_dir
   pwclient list

This command returns the list of patches sent to alpine-aports@lists.alpinelinux.org and injected in patchwork workflow.

look at the patch:

   pwclient view $PATCH_ID.

Let's assume is 66:

   pwclient view 66

host:~/aports$ pwclient view 66
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [alpine-aports] testing/proxychains-ng: install and install-config
 returns 1 in case of error
From: Francesco Colista <fcolista@alpinelinux.org>
X-Patchwork-Id: 66
Message-Id: <1430294296-26952-1-git-send-email-fcolista@alpinelinux.org>
To: alpine-aports@lists.alpinelinux.org
Cc: Francesco Colista <fcolista@alpinelinux.org>
Date: Wed, 29 Apr 2015 07:58:16 +0000

---
 testing/proxychains-ng/APKBUILD | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/testing/proxychains-ng/APKBUILD b/testing/proxychains-ng/APKBUILD
index 463a2ac..b40ba25 100644
--- a/testing/proxychains-ng/APKBUILD
+++ b/testing/proxychains-ng/APKBUILD
@@ -2,7 +2,7 @@
 # Maintainer: Francesco Colista <fcolista@alpinelinux.org>
 pkgname=proxychains-ng
 pkgver=4.8.1
-pkgrel=0
+pkgrel=1
 pkgdesc="This tool provides proxy server support to any app."
 url="https://github.com/rofl0r/proxychains-ng"
 arch="all"
@@ -36,8 +36,7 @@ build() {
 
 package() {
        cd "$_builddir"
-       make DESTDIR="$pkgdir" install
-       make DESTDIR="$pkgdir" install-config
+       make DESTDIR="$pkgdir" install install-config || return 1
        ln -s proxychains4 "$pkgdir"/usr/bin/proxychains
 }

If it looks fine, try to apply the patch, first, in your git tree, and test it.

There are three ways to apply patch in the local tree. We are going to show all of them...then choose what is more fitting for you.

.1 pwclient apply

Note: pwclient apply command apply patch using -p1. So patch is applied starting from the current dir.

   pwclient apply 66

This apply patch in your local git tree. Then you can:

   abuild -r.

If patch is ok, then you need to reset the your git tree (because it got modified by applying the patch). so:

   git checkout --

then

   pwclient git-am 66

this apply and commit the patch in one shot.

Last step is pushing the change to git repo with:

   git pull--rebase && git push

.2 pwclient get

   pwclient get 66

update the APKBUILD in order to apply the patch, then build it with the usual:

   abuild -r

If patch is ok, then you need to reset the your git tree (because it got modified by applying the patch). so:

   git checkout --

then

   pwclient git-am 66

this apply and commit the patch in one shot.

Last step is pushing the change to git repo with:

   git pull--rebase && git push

.3 pwclient git-am

This can be done by:

   pwclient git-am 66

Since this command aply and commits directly as already stated before, the last step is pushing the change to git repo with:

   git pull--rebase && git push 

Patch does not apply. And now?

If you have used

   pwclient apply

or

   pwclient get

Then you shoud go for:

   git checkout

If you have used

   pwclient git-am

Then patch is committed, so you need to

   git reset HEAD@{1}

This uses the last entry in the reflog. If you did other things in between, look at:

   git reflog

to see which number corresponds to which commit.

Oh, looks that someone else already applied the patch while i was going to do it. Now, when i try to git pull --rebase, i got: "It looks like git-am is in progress. Cannot rebase." and now?

   git am --abort

I sent a patch that was already applied.

At the moment, patchwork does not allow to comment reasons for a state change (it's in their todo list)

So, we can simple set it as "Not Applicable" (since "Duplicate" does not exists)

My patch got rejected.

You'll be alerted via email about that. You can ask why patch is got rejected on #alpine-devel IRC channel.