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
|
[[!meta title="Sending patches to vmdb2"]]
vmdb2 is a free software project and has an associated website. This
page explains how you can contribute changes to either.
[git]: https://git-scm.com/
[git.liw.fi]: http://git.liw.fi/
[gitlab]: https://gitlab.com/larswirzenius/vmdb2
[vmdb2]: http://git.liw.fi/vmdb2/
[vmdb2.liw.fi]: http://git.liw.fi/vmdb2.liw.fi
[Gitano]: https://www.gitano.org.uk/
[free software should use free tools]: https://mako.cc/writing/hill-free_tools.html
We use the [git][] version control system. Our repositories are hosted
on a [git.liw.fi][], a personal server hosted by Lars Wirzenius, using
the [Gitano][] software. See the [vmdb2][] and [vmdb2.liw.fi][]
repositories.
An identical repository is hosted on [gitlab][] for those who prefer
the merge-request based workflow. GitLab is not entire free software,
but "open core", and [free software should use free tools][].
We want to make it easy for you to send us patches.
Here's a few ways you can send us changes:
* Tell us in your own free words what the proposed change is, over
e-mail or another medium. We can do the change in git ourselves, if
we agree to the change. This is good for small changes, such as
wording changes, or such.
If you don't know how to use git, use this method. It's low tech,
but also low friction to you, even if a little more work for us.
* Send us changes formatted with "git format-patch", over email to
liw@liw.fi. (Using "git send-email" is good, too.)
If you're sending a patch series consisting of several patches,
add a "cover letter" that expolains what the whole series is about.
* Make the changes available on a different git server, and send us a
URL we can pull from. You can use GitHub or any other server that's
convenient for you. You can even create a pull request and send a
link to that.
# On patches (and pull requests and merge requests)
We prefer a patch series and pull request to tell a story of the
change that is easy to follow and review and understand.
* Each patch/commit should have a clear commit message. The commit
message should explain why the change is made, and not just rephrase
the diff. The commit message should stand on its own, as it will be
read on its own in the future, when someone is debugging the
program, possibly with "git bisect".
* The commit message should follow the [this guide][], and
additionally the first summary line should start with one of the
words "Add", "Change", "Drop", or "Refactor".
* Each patch/commit should change only one logical thing at a time. It
should also not be semantically large: avoid changing many parts of
the code at once, unless it's trivial changes like renaming a class.
Do such renames in a patch/commit that makes no other changes.
* Don't squash commits into one for a pull request.
* If necessary, clean up the branch/pull request with "git rebase -i"
to produce something that's clear and easy to review.
* Remember to update the NEWS file for any changes visible to the user
or system administrator.
[this guide]: https://chris.beams.io/posts/git-commit/
|
