Development using git:Creating patches: Difference between revisions

From Alpine Linux
m (fix typo in alpine-devel address)
m (Prabuanand moved page Creating patches to Development using git:Creating patches: Moving all alpine Development using git related pages to single page for easier referencing )
 
(28 intermediate revisions by 11 users not shown)
Line 1: Line 1:
There are several possible ways to send patches. Below the most common are described.  
New aports should normally go into testing repository. After a reasonable testing period if the package is complete (e.g. it has an init script, it has a working and sane default configuration, etc.) and it has a maintainer it can be moved into community repository. Main repository is for packages that are either core of the linux system or are dependencies of other core packages. A package in main cannot have a dependency in community or testing and a package in community cannot have a dependency on packages in testing.


== Only the last commit with 'git send-email' ==
There are currently two ways to contribute to propose changes, via Gitlab and via the mailing list.


To submit the last commit as a patch to alpine-devel mailing list:
== Submitting patches via Gitlab ==


{{Cmd|git send-email --to alpine-devel@lists.alpinelinux.org HEAD^}}
=== Setup ===
 
To submit patches on [https://gitlab.alpinelinux.org Alpine Linux' Gitlab instance] you first have to create an account for it [https://gitlab.alpinelinux.org/users/sign_in here]. It's recommended to set a SSH key now, refer to the [https://docs.gitlab.com/ee/ssh/ Gitlab docs] for how to do that.
 
=== Creating a merge request ===
 
Now that you're all setup you have to fork the repository you want to contribute to, for example if you want to open a merge request for aports you would have to fork [https://gitlab.alpinelinux.org/alpine/aports alpine/aports], see the [https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork Gitlab docs] if you're having problems with that. Other repositories belonging to Alpine Linux live in the [https://gitlab.alpinelinux.org/alpine Alpine organisation]. If you already have an old fork, first clone it and then update it as shown below.
 
After forking you can clone the repository like so:
 
{{Cmd|git clone git@gitlab.alpinelinux.org:$USER/$REPO.git}}
 
Replace $USER with the nickname of your Gitlab account and $REPO with the repository you want to work on. Now you can change to another branch (e.g. the name of the package you want to edit) with:
 
(If necessary, update an old fork first, see [[#Rebasing against Alpine Linux's master|rebasing]], below)
 
{{Cmd|git checkout -b pkgname}}
 
Do your changes now and then push with:
 
{{Cmd|git push -u origin $branchname }}
 
Gitlab will print an URL to create a merge request in your terminal.
 
=== Amending changes to a merge request ===
 
If reviewers requested changes or if you noticed that something should be changed about your merge request's change you can simply amend your changes to the right commit and force push. So if you want to change the commit at the tip of your branch you can simply do:
 
{{Cmd|git commit --amend}}
 
If you want to change a commit that's not at the tip of your branch you can do:
 
{{Cmd|git commit --fixup $SHA1_OF_COMMIT_YOU_WANT_TO_FIX}}
 
Afterwards you have to force-push in order to update your merge request:
 
{{Cmd|git push -f origin}}
 
=== Rebasing against Alpine Linux's master ===
 
It's best to always stay up-to-date with the state of the upstream Alpine Linux repository to ensure that no merge conflicts happen later on. To do that you first have to add a new git remote which points to the upstream repository (instead of your fork):
 
{{Cmd|git remote add upstream <nowiki>https://gitlab.alpinelinux.org/alpine/$REPO</nowiki>}}
 
Now you can fetch all changes with:
 
{{Cmd|git fetch --all}}
 
And then you can rebase with:
 
{{Cmd|git rebase}}
 
== Submitting patches via the mailing list ==
{{Warning|Submitting patches via the mailing list is currently broken as-of 15 August 2023}}
 
Patches should be created with git and submitted to [mailto:alpine-aports@lists.alpinelinux.org alpine-aports] mailing list with ''git send-email'' (which needs the ''git-email'' Alpine package).
 
=== Only the last commit with 'git send-email' ===
 
To submit the last commit as a patch to [mailto:alpine-aports@lists.alpinelinux.org alpine-aports] mailing list:
 
{{Cmd|git send-email --to alpine-aports@lists.alpinelinux.org -1}}
 
{{Tip|You save the To-address (does not require '--to alpine-aports@lists.alpinelinux.org') in the git config with: {{Cmd|git config sendemail.to alpine-aports@lists.alpinelinux.org}}}}


The first line in commit message will be ''subject'' and the long description (separated with empty line) will be the body in the email. The example below shows  
The first line in commit message will be ''subject'' and the long description (separated with empty line) will be the body in the email. The example below shows  


<pre>
<pre>
Initial APKBUILD file of packagename <- Subject line
testing/packagename: new aport <- header


Enter some details about your package <- Mail body
https://example.com/packagename <- body
here if you like.
wonderful package
</pre>
</pre>


{{Note|The git send-email command is provided by the '''git-perl''' package. }}
{{Note|The git send-email command is provided by the '''git-email''' package ('''git-perl''' in v2.7 and older). }}


Read [[Development using git]] to send patch with SMTP Auth.
See [[Development using git#Email_configuration]] on how configure SMTP Auth.


== Multiple commits with 'git send-email' ==
=== Multiple commits with 'git send-email' ===


If you have many commits you can create a directory with patches and send them with <tt>git send-email</tt>.
If you have many commits you can create a directory with patches and send them with <tt>git send-email</tt>.
Line 27: Line 90:
mkdir patches
mkdir patches
git format-patch -o patches origin
git format-patch -o patches origin
git send-email --compose --no-chain-reply-to --to alpine-devel@lists.alpinelinux.org</nowiki>}}
git send-email patches --compose --no-chain-reply-to --to alpine-aports@lists.alpinelinux.org</nowiki>}}
 
You can also format patches for the last x number of commits with:
{{Cmd|<nowiki>git format-patch -x -o patches</nowiki>}}


This will produce the patches for each local commit in the directory "patches" and send them.
This will produce the patches for each local commit in the directory "patches" and send them.
Use --no-chain-reply-to make sure it doesn't reply.
Use '''--no-chain-reply-to''' to avoid that each patch is sent as a ''reply'' to the previous patch.


<!-- what does the following mean? -->
Eg.
Don't do:
* [PATCH 0/m]
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 1/m]
*** [PATCH 2/m]
*** [PATCH 2/m]
**** ...
**** ...
But do:
 
With the option '''--no-chain-reply-to''' the patches will be sent as a reply to the first email, the ''cover letter'' (the [PATCH 0/m]) and will make the email thread nicer.
Like this:
* [PATCH 0/m]
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 1/m]
Line 44: Line 111:
** ..
** ..


== Multiple patches with 'email' ==
=== Resend an updated patch ===
Sometimes patches are rejected due to minor issues in the patch. Do not send an incremental patch on top of your initial, bad, patch. Instead, recreate the patch and send a new, fixed version of your patch. (use ''git commit --amend'' to edit a local commit).


{{Cmd|git format-patch -1}}
When you sending a second version of the patch use '''--subject-prefix "PATCH v2"''' to indicate that this is a new version of a previously sent patch. You may also use '''--in-reply-to <message-id>''' where <message-id> the the id of email requesting the resend.


Where -1 sets how many commits you want to go back (mostly this is 1). This should create a patch called 0001......patch.  
You should also write a note on the what was changed. Use '''--annotate''' for this and write the comment under the three dashes "---" so the note is not included in the commit message. For example:
<pre>
...
Subject: [PATCH v2] testing/mypackage: new aport


An easy way to send this patch to the list is with an program called 'email'.
https://example.com
Example package
---
Changes v1 -> v2:
- removed depends
- added zlib-dev to makedepends


{{Cmd|apk add email}}
testing/mypackage/APKBUILD | 41 +++++++++++++++++++++++++++++++++++++++++
 
1 file changed, 41 insertions(+)
to send to the mailing list you would do:
create mode 100644 testing/mypackage/APKBUILD
 
...
{{Cmd|email -a 0001...patch alpine-devel@lists.alpinelinux.org}}
</pre>


And provide a subject and body after you execute the above cmd.
Note that the notes that are below the "---" will not be included in the commit message.
[[Category:Development]]
[[Category:Git]]

Latest revision as of 10:10, 14 August 2024

New aports should normally go into testing repository. After a reasonable testing period if the package is complete (e.g. it has an init script, it has a working and sane default configuration, etc.) and it has a maintainer it can be moved into community repository. Main repository is for packages that are either core of the linux system or are dependencies of other core packages. A package in main cannot have a dependency in community or testing and a package in community cannot have a dependency on packages in testing.

There are currently two ways to contribute to propose changes, via Gitlab and via the mailing list.

Submitting patches via Gitlab

Setup

To submit patches on Alpine Linux' Gitlab instance you first have to create an account for it here. It's recommended to set a SSH key now, refer to the Gitlab docs for how to do that.

Creating a merge request

Now that you're all setup you have to fork the repository you want to contribute to, for example if you want to open a merge request for aports you would have to fork alpine/aports, see the Gitlab docs if you're having problems with that. Other repositories belonging to Alpine Linux live in the Alpine organisation. If you already have an old fork, first clone it and then update it as shown below.

After forking you can clone the repository like so:

git clone git@gitlab.alpinelinux.org:$USER/$REPO.git

Replace $USER with the nickname of your Gitlab account and $REPO with the repository you want to work on. Now you can change to another branch (e.g. the name of the package you want to edit) with:

(If necessary, update an old fork first, see rebasing, below)

git checkout -b pkgname

Do your changes now and then push with:

git push -u origin $branchname

Gitlab will print an URL to create a merge request in your terminal.

Amending changes to a merge request

If reviewers requested changes or if you noticed that something should be changed about your merge request's change you can simply amend your changes to the right commit and force push. So if you want to change the commit at the tip of your branch you can simply do:

git commit --amend

If you want to change a commit that's not at the tip of your branch you can do:

git commit --fixup $SHA1_OF_COMMIT_YOU_WANT_TO_FIX

Afterwards you have to force-push in order to update your merge request:

git push -f origin

Rebasing against Alpine Linux's master

It's best to always stay up-to-date with the state of the upstream Alpine Linux repository to ensure that no merge conflicts happen later on. To do that you first have to add a new git remote which points to the upstream repository (instead of your fork):

git remote add upstream https://gitlab.alpinelinux.org/alpine/$REPO

Now you can fetch all changes with:

git fetch --all

And then you can rebase with:

git rebase

Submitting patches via the mailing list

Warning: Submitting patches via the mailing list is currently broken as-of 15 August 2023


Patches should be created with git and submitted to alpine-aports mailing list with git send-email (which needs the git-email Alpine package).

Only the last commit with 'git send-email'

To submit the last commit as a patch to alpine-aports mailing list:

git send-email --to alpine-aports@lists.alpinelinux.org -1

Tip: You save the To-address (does not require '--to alpine-aports@lists.alpinelinux.org') in the git config with:

git config sendemail.to alpine-aports@lists.alpinelinux.org

The first line in commit message will be subject and the long description (separated with empty line) will be the body in the email. The example below shows

testing/packagename: new aport <- header

https://example.com/packagename <- body
wonderful package
Note: The git send-email command is provided by the git-email package (git-perl in v2.7 and older).

See Development using git#Email_configuration on how configure SMTP Auth.

Multiple commits with 'git send-email'

If you have many commits you can create a directory with patches and send them with git send-email.

rm -Rf patches mkdir patches git format-patch -o patches origin git send-email patches --compose --no-chain-reply-to --to alpine-aports@lists.alpinelinux.org

You can also format patches for the last x number of commits with:

git format-patch -x -o patches

This will produce the patches for each local commit in the directory "patches" and send them. Use --no-chain-reply-to to avoid that each patch is sent as a reply to the previous patch.

Eg.

  • [PATCH 0/m]
    • [PATCH 1/m]
      • [PATCH 2/m]
        • ...

With the option --no-chain-reply-to the patches will be sent as a reply to the first email, the cover letter (the [PATCH 0/m]) and will make the email thread nicer. Like this:

  • [PATCH 0/m]
    • [PATCH 1/m]
    • [PATCH 2/m]
    • ..

Resend an updated patch

Sometimes patches are rejected due to minor issues in the patch. Do not send an incremental patch on top of your initial, bad, patch. Instead, recreate the patch and send a new, fixed version of your patch. (use git commit --amend to edit a local commit).

When you sending a second version of the patch use --subject-prefix "PATCH v2" to indicate that this is a new version of a previously sent patch. You may also use --in-reply-to <message-id> where <message-id> the the id of email requesting the resend.

You should also write a note on the what was changed. Use --annotate for this and write the comment under the three dashes "---" so the note is not included in the commit message. For example:

...
Subject: [PATCH v2] testing/mypackage: new aport

https://example.com
Example package
---
Changes v1 -> v2:
 - removed depends
 - added zlib-dev to makedepends

 testing/mypackage/APKBUILD | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 testing/mypackage/APKBUILD
...

Note that the notes that are below the "---" will not be included in the commit message.