1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
# Contributing to Offpunk
If you are familiar with Python and Git, contributing to Offpunk is probably a lot easier than it appears.
And if you are not a programmer, but still want to help, you can always help with offpunk's translation. Keep reading this page to get an idea of how to clone the repo, and how to send a patch. And then read the translation howto:
=> ./translation.gmi Learn how to help with translations
## Joining the project
The project is currently hosted on Sourcehut.
=> https://sr.ht/~lioploum/offpunk/ Offpunk on Sourcehut
All the technical discussions happen on the Offpunk-devel mailing list.
=> https://lists.sr.ht/~lioploum/offpunk-devel Offpunk-devel mailing-list archives
It is also currently the best place to report a bug or ask a technical question. No need to create an account, simply send an email to the list.
=> mailto:~lioploum/offpunk-devel@lists.sr.ht Send an email to offpunk-devel
IMPORTANT: when replying to a message on the list, be sure to use the "reply all". If you forget, only the original sender will receive your message.
Also, emails should be sent in plaintext, not in HTML.
=> https://useplaintext.email/ Use plaintext email (useplaintext.email)
If you plan to interact for more than one issue, its probably a good idea to subscribe to the list. Volume is relatively low and there’s no need to create any account.
=> mailto:~lioploum/offpunk-devel+subscribe@lists.sr.ht Subscribe to Offpunk-devel
## Making your first contribution
The first step is, of course, to clone the git repository on your computer and check if you can run it locally without trouble.
```
git clone https://git.sr.ht/~lioploum/offpunk
cd offpunk
./offpunk.py
version
```
Now, you can simply explore the source code by yourself or by asking questions on the mailing-list. One good opportunity to learn is to improve this tutorial that you will find in the "tutorial" folder. You can also add your own Offpunk workflow.
Once it’s done, commit your change locally. Don’t forget to give a good description to your commit when asked.
```
git add PATH_TO_MODIFIED_FILE
git commit
```
Try to keep your modifications in one meaningful commit. If you change something after the commit, simply amend it.
```
git commit -a --amend
```
Once you are satisfied with your commit, it’s time to send it.
Offpunk doesn’t use Github. There’s no Pull Requests and web interface. Instead, your commit will be sent as a patch by email. Don’t worry, it is easier than it looks.
If it’s the first time you send a git patch by email, your computer may requires some configuration. Follow the git-send-email tutorial.
=> https://git-send-email.io/ Learn to use email with git! (git-send-email.io)
If it is not sufficient, some informations could be found on the Linux kernel development documentation. In most cases, this is not needed.
=> https://docs.kernel.org/process/email-clients.html How to configure your mail client (kernel.org)
Now, in your local offpunk folder, we will set offpunk-devel list as the default destination for patches. This should only be done once.
```
git config sendemail.to "~lioploum/offpunk-devel@lists.sr.ht"
```
Now, we are ready to send the latest commit as a patch.
```
git send-email HEAD^
```
That’s it! Your first patch to Offpunk is sent!
## Improving the patch
In most cases, the patch need to be discussed. This happens on the list itself, commenting the code by emails. You will probably receive suggestions on how to improve the patch. Modify your code accordingly then amend your commit.
```
git commit -a --amend
```
Once ready, send us the v2 of your patch by labelling it as such.
```
git send-email --annotate -v2 HEAD^
```
The version 2 of your patch should be sent as a new email in its own thread. Don’t reply to the previous thread (which is what the Linux Kernel is recommending because they are way bigger than Offpunk).
There can of course be a v3, v4, etc. What is important is to clearly communicate if you plan to work on a new version of the patch, if you consider that it should be merged as is or if you abandon the work on the subject for now.
There’s no pressure. We all do this for fun. We simply need to communicate clearly.
Also, mistakes happen. We all do mistakes. Your duty is inform the list as soon as you realize you did a mistake. We’ve all sent wrong emails or patches. That’s not a problem. But it may become a problem if people start working on reviewing code that was sent by mistake.
## Rebasing your patches into one
If your work takes longer than expected, you will probably makes multiple commits and other commits may happen on TRUNK. We recomment that you work in a local branch. You must give it a name.
```
git branch my_super_feature
git checkout my_super_feature_branch
```
You can easily switch between "master" (the official branck) and your own branch through "git checkout".
When you are ready to submit, first make sure that "master" is up to date
```
git checkout master
git pull
```
Then you will merge your branch into that clean master. We recommend using "git-squash" which will automatically combines everything into one single commit. "git-squash" is often not installed by default, it is part of the "git-extras" package, available on most distributions. It is of course possible to do more traditional "git-merge" or "git-rebase".
```
git squash my_super_feature_branch
```
By default, those changes are not committed. It’s time to write a very informative commit message because that’s the one that wille be used in your email
```
git commit
git send-email HEAD^
```
You may need to solve conflicts in order to conclude the rebase. You may find the following article helpful:
=> https://www.brethorsting.com/blog/2026/01/git-rebase-for-the-terrified/ Git Rebase for the Terrified (www.brethorsting.com)
## After your patch was accepted
Once your patch is accepted, it will be both local and upstream.
First do
```
git pull
```
You will be warned that your git branches have diverged. But, in reality, they diverged with the same patch on each side. You can simply resolve this with:
```
git rebase
```
|
