Alpine Linux - User contributions [en]

Git

2023-08-23T06:47:51Z

CarloMonte:

{{Move|Git|All git development articles should be consolidated}}

This document describes how to use [https://git-scm.com git] for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].

== Basic Git usage ==

{{:Development_using_git:Configuration}}

{{Tip| If you want to use git with colored output use:
{{Cmd|git config --global color.ui true
git config --global core.pager more}}
}}

{{Tip| If you want to use git with proxy server:
{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}
}}

== Cloning a repository via Git ==

There are two ways to work with the Alpine git repository...

* ...without write access.
* ...with write access.

[https://git.alpinelinux.org/aports git.alpinelinux.org] shows all available Alpine git repositories.

=== Without write access ===

If you want to clone the Alpine aports repository, switch to the directory you want to have the ''aports/'' directory in and launch git.

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

{{Tip| If you are using proxy server:
{{Cmd|git clone https://git.alpinelinux.org/aports}}
}}

If you want only the last 3 revisions:

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}

Use the command below to see the full log of the trunk.

{{Cmd|git log}}

=== Submitting work without write access ===

You can still [https://wiki.alpinelinux.org/wiki/Creating_patches submit a patch] without write access to the Alpine repository. For this you need to create an account on Alpine's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the squashed branch to the fork (as branch; do not merge/rebase it into the master!) and create a merge request for that branch through the GitLab Web GUI.

=== With write access ===

If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository

{{Cmd|git clone git@git.alpinelinux.org:aports}}

Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}

== General GIT Workflow ==
# Make your file edits in your local checkout of the local copy of repository.
# Commit the changes in your local repository: {{Cmd|git commit}}
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
# Check what you are going to push: {{Cmd|git log origin..master}}
# Move your changes up to the master if you have write access {{Cmd|git push}} or [[Creating_patches|create a patch]] if not.

== Other related articles ==

* [[Development_using_git:Basic_usage| Basic usage]]
* [[Package Maintainers]]
* [[Creating patches]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Development using git:Quality assurance]]
* [[Gitolite]]

== Further reading ==
{{:Development_using_git:Documentation}}

[[Category:Development]]
[[Category:Git]]

Patch Workflow

2023-08-16T06:44:43Z

CarloMonte: /* My patch got rejected. */

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: [https://sourceware.org/glibc/wiki/Patch%20Review%20Workflow]

== 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

<pre>
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
}
</pre>

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.

[[Category:Development]]
[[Category:Git]]

Udhcpc

2023-08-16T06:42:39Z

CarloMonte:

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example of <code>udhcpc_opts</code> in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

The default configuration of <code>udhcpc</code> may be overridden by <code>/etc/udhcpc/udhcpc.conf</code>. Please see <code>/usr/share/udhcpc/default.script</code> for how the values are used.

<code>udhcpc.conf</code> accepts the following key:value pairs:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
| meaning
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
| do not overwrite or alternative path for resolv.conf
|-
| NO_DNS
| -
| <list of iface names>
| Prevent overwriting of resolv.conf on a per-interface basis
|-
| NO_GATEWAY
| -
| <list of iface names>
| List of interfaces where DHCP routes are ignored
|-
| IF_METRIC
| -
| <metric value>
| offset value for routing metric
|-
| IF_PEER_DNS
| yes
| <anything but yes>
| please use RESOLV_CONF or NO_DNS instead
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2023-08-16T06:41:00Z

CarloMonte:

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example of <code>udhcpc_opts</code> in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

The default configuration of <code>udhcpc</code> may be overridden by <code>/etc/udhcpc/udhcpc.conf</code>. Please see <code>/usr/share/udhcpc/default.script</code> for how the values are used.

Authorized key:value pairs for <code>udhcpc.conf</code> are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
| meaning
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
| do not overwrite or alternative path for resolv.conf
|-
| NO_DNS
| -
| <list of iface names>
| Prevent overwriting of resolv.conf on a per-interface basis
|-
| NO_GATEWAY
| -
| <list of iface names>
| List of interfaces where DHCP routes are ignored
|-
| IF_METRIC
| -
| <metric value>
| offset value for routing metric
|-
| IF_PEER_DNS
| yes
| <anything but yes>
| please use RESOLV_CONF or NO_DNS instead
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Git

2023-08-15T17:29:17Z

CarloMonte:

{{Move|Git|All git development articles should be consolidated}}

This document describes how to use [https://git-scm.com git] for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].

== Basic Git usage ==

{{:Development_using_git:Configuration}}

{{Tip| If you want to use git with colored output use:
{{Cmd|git config --global color.ui true
git config --global core.pager more}}
}}

{{Tip| If you want to use git with proxy server:
{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}
}}

== Cloning a repository via Git ==

There are two ways to work with the Alpine git repository...

* ...without write access.
* ...with write access.

[https://git.alpinelinux.org/aports git.alpinelinux.org] shows all available Alpine git repositories.

=== Without write access ===

If you want to clone the Alpine aports repository, switch to the directory you want to have the ''aports/'' directory in and launch git.

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

{{Tip| If you are using proxy server:
{{Cmd|git clone https://git.alpinelinux.org/aports}}
}}

If you want only the last 3 revisions:

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}

Use the command below to see the full log of the trunk.

{{Cmd|git log}}

=== Submitting work without write access ===

You can still [https://wiki.alpinelinux.org/wiki/Creating_patches submit a patch] without write access to the Alpine repository. For this you need to create an account on Alpine's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the branch to the fork (as branch; do not merge/rebase it into the master!) and create a merge request for that branch through the GitLab Web GUI.

=== With write access ===

If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository

{{Cmd|git clone git@git.alpinelinux.org:aports}}

Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}

== General GIT Workflow ==
# Make your file edits in your local checkout of the local copy of repository.
# Commit the changes in your local repository: {{Cmd|git commit}}
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
# Check what you are going to push: {{Cmd|git log origin..master}}
# Move your changes up to the master if you have write access {{Cmd|git push}} or [[Creating_patches|create a patch]] if not.

== Other related articles ==

* [[Development_using_git:Basic_usage| Basic usage]]
* [[Package Maintainers]]
* [[Creating patches]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Development using git:Quality assurance]]
* [[Gitolite]]

== Further reading ==
{{:Development_using_git:Documentation}}

[[Category:Development]]
[[Category:Git]]

Git

2023-08-15T16:35:45Z

CarloMonte: /* Submitting work without write access */

{{Move|Git|All git development articles should be consolidated}}

This document describes how to use [https://git-scm.com git] for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].

== Basic Git usage ==

{{:Development_using_git:Configuration}}

{{Tip| If you want to use git with colored output use:
{{Cmd|git config --global color.ui true
git config --global core.pager more}}
}}

{{Tip| If you want to use git with proxy server:
{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}
}}

== Cloning a repository via Git ==

There are two ways to work with the Alpine git repository...

* ...without write access.
* ...with write access.

[https://git.alpinelinux.org/aports git.alpinelinux.org] shows all available Alpine git repositories.

=== Without write access ===

If you want to clone the Alpine aports repository, switch to the directory you want to have the ''aports/'' directory in and launch git.

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

{{Tip| If you are using proxy server:
{{Cmd|git clone https://git.alpinelinux.org/aports}}
}}

If you want only the last 3 revisions:

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}

Use the command below to see the full log of the trunk.

{{Cmd|git log}}

=== Submitting work without write access ===

You can still [https://wiki.alpinelinux.org/wiki/Creating_patches submit a patch] without write access to the Alpine repository. For this you need to create an account on Alpine's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the branch and create a merge request for that branch through the GitLab Web GUI.

=== With write access ===

If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository

{{Cmd|git clone git@git.alpinelinux.org:aports}}

Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}

== General GIT Workflow ==
# Make your file edits in your local checkout of the local copy of repository.
# Commit the changes in your local repository: {{Cmd|git commit}}
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
# Check what you are going to push: {{Cmd|git log origin..master}}
# Move your changes up to the master if you have write access {{Cmd|git push}} or [[Creating_patches|create a patch]] if not.

== Other related articles ==

* [[Development_using_git:Basic_usage| Basic usage]]
* [[Package Maintainers]]
* [[Creating patches]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Development using git:Quality assurance]]
* [[Gitolite]]

== Further reading ==
{{:Development_using_git:Documentation}}

[[Category:Development]]
[[Category:Git]]

Git

2023-08-15T16:35:05Z

CarloMonte:

{{Move|Git|All git development articles should be consolidated}}

This document describes how to use [https://git-scm.com git] for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].

== Basic Git usage ==

{{:Development_using_git:Configuration}}

{{Tip| If you want to use git with colored output use:
{{Cmd|git config --global color.ui true
git config --global core.pager more}}
}}

{{Tip| If you want to use git with proxy server:
{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}
}}

== Cloning a repository via Git ==

There are two ways to work with the Alpine git repository...

* ...without write access.
* ...with write access.

[https://git.alpinelinux.org/aports git.alpinelinux.org] shows all available Alpine git repositories.

=== Without write access ===

If you want to clone the Alpine aports repository, switch to the directory you want to have the ''aports/'' directory in and launch git.

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

{{Tip| If you are using proxy server:
{{Cmd|git clone https://git.alpinelinux.org/aports}}
}}

If you want only the last 3 revisions:

{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}

Use the command below to see the full log of the trunk.

{{Cmd|git log}}

=== Submitting work without write access ===

You can still [https://wiki.alpinelinux.org/wiki/Creating_patches submit a patch] without write access to the Alpine repository. For this you need to create an account on Aline's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the branch and create a merge request through the GitLab Web GUI.

=== With write access ===

If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository

{{Cmd|git clone git@git.alpinelinux.org:aports}}

Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}

== General GIT Workflow ==
# Make your file edits in your local checkout of the local copy of repository.
# Commit the changes in your local repository: {{Cmd|git commit}}
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
# Check what you are going to push: {{Cmd|git log origin..master}}
# Move your changes up to the master if you have write access {{Cmd|git push}} or [[Creating_patches|create a patch]] if not.

== Other related articles ==

* [[Development_using_git:Basic_usage| Basic usage]]
* [[Package Maintainers]]
* [[Creating patches]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Development using git:Quality assurance]]
* [[Gitolite]]

== Further reading ==
{{:Development_using_git:Documentation}}

[[Category:Development]]
[[Category:Git]]

Creating patches

2023-08-15T15:14:37Z

CarloMonte:

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 [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 https://gitlab.alpinelinux.org/alpine/$REPO}}

Now you can fetch all changes with:

{{Cmd|git fetch --all}}

And then you can rebase with:

{{Cmd|git rebase}}

== BROKEN AS OF 2023-08: Submitting patches via the mailing list ==

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

<pre>
testing/packagename: new aport <- header

https://example.com/packagename <- body
wonderful package
</pre>

{{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 <tt>git send-email</tt>.

{{Cmd|<nowiki>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</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.
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:
<pre>
...
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
...
</pre>

Note that the notes that are below the "---" will not be included in the commit message.
[[Category:Development]]
[[Category:Git]]