summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
blob: a471d497ab046bfdedf31a1cca3ec23fcc9b890a (plain)
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
# Contributing to imag

So you want to contribute to imag! Thank you, that's awesome!

If you already have something in mind, go ahead with [the prerequisites
section](#prerequisites). If you don't know what you could do, start here.

All contributors agree to the
[developer certificate of origin](#developer-certificate-of-origin)
by contributing to imag.

## Without Github

If you do not want to use github for your contribution, this is completely okay.
Feel free to contact [us via our mailinglist](http://imag-pim.org/mailinglist/)
via mail, feel also free to submit patches via mail (use `git format-patch` and
`git send-email`, always add a cover letter to describe your submission).

Also ensure that each commit has
[a "Signed-off-by: " line](https://stackoverflow.com/questions/1962094/what-is-the-sign-off-feature-in-git-for).
By adding that line, you agree to our
[developer certificate of origin](#developer-certificate-of-origin).

Once _I am_ okay with your patchset, I will
submit it as PR in the github repository, so more people can review it and CI
can test it (the mailinglist is not yet used as much as github). I might come
back to you if something broke in CI or someone has a suggestion how to improve
your PR. I will keep you as author of the commits.

The following sections describe the way how to contribute with github.

## Finding an issue

Finding an issue is simple: We have
[a special label in our issues section](https://github.com/matthiasbeyer/imag/issues?q=is%3Aissue+is%3Aopen+label%3Acomplexity%2Feasy)
for easy-to-solve issues. You can start there, don't hesitate to ask questions
if you do not understand the issue comment!

Also, if you found bugs or outdated stuff in our documentation, feel free to
file issues about them or even better: Write a pull request to fix them!

## Prerequisites

* cargo and rust compiler in current version (stable)
* Ruby and Bundler if you want to write a Ruby module.

Dependencies are listed in the
[default.nix file](http://git.imag-pim.org/imag/tree/default.nix),
though you do not have to have `nix` installed to build imag.

`make` can be helpful to automate the build process.

Note that this software is targeted towards commandline linux users and we do
not aim to be portable to Windows or Mac OSX (though I wouldn't mind merging
patches for OS X compatibility).

* If you want to build the documentation (you don't have to)
  * pandoc
  * pandoc-citeproc
  * texlive
  * lmodern (font package)
  * make

All dependencies are installable with the nix package manager by using a
`nix-shell`, if you have the nix package manager installed on your system.

## Commit guidelines

Please don't refer to issues or PRs from inside a commit message, if possible.
Make sure your PR does not contain "Fixup" commits when publishing it, but feel
free to push "Fixup" commits in the review process. We will ask you to clean
your history before merging!

Make sure to prefix your commits with `"doc: "` if you change the document. Do
not change document and code in one commit, always separate them.

We do not follow some official Rust styleguide for our codebase, but we try to
write minimal and readable code. 100 characters per line, as few lines as
possible, avoid noise in the codebase, ... you get it.

Not all of your commits have to be buildable. But your PR has to be.

## PR guidelines

We'd like to have one PR per module change. This means you _should_ only change
one imag module in one commit or PR (library plus belonging binary is okay).
As this is not always possible, we do not enforce this, though we might ask you
to split your commits/PR into two smaller ones.

Use feature branches. If you could name them "<module name>/<what you do>",
for example "libimagstore/add-debugging-calls", that would be awesome.

You are welcome to publish your PR as soon as there is one commit in your
branch. This gives us the possibility to review whether your ideas go into a
nice direction or whether there are issues with your approach and we can report
them to you rather quickly. Rewriting a whole PR is not satisfactory and we'd
like to make your contribution process enjoyable.

# Merging tools which use the imag core functionality into this repo

If you're writing an application or module for imag, feel free to propose
integrating it into the imag core distribution, if it fulfills the following
requirements:

1. It is written in Rust or Ruby
1. It has a commandline interface which is the main interface to the module
   OR it is a utility library for creating new kinds of functionality within the
   imag core.
1. It is licensed under the terms of GNU LGPLv2.1 OR all of your contributors
   approve a commit which changes the license of your codebase to GNU LGPLv2.1
   (The word "approve" in this sentence is to be defined).

(If your tool does not fulfill these requirements, I won't merge it into the
imag core distribution.)

## Code of Conduct

We use the same
[code of conduct as the rust community does](https://www.rust-lang.org/conduct.html).

Basically: Be kind, encourage others to ask questions - you are encouraged to
ask questions as well!

## Contact

Feel free to reach out via mail/[mailinglist](http://imag-pim.org/mailinglist/)
or [IRC](irc://irc.freenode.net/#imag).

## More information about the structure of this project

Here goes some notes on how this project is structured.

### Issue- and PR-Labels

Our labels are color coded as well as "namespaced". The color groups labels
exactly as the prefix does. The prefix is the first component which is seperated
from the others by `"/`". See below:

| Label                     | Description                       | search                                     |
| ---                       | ---                               | ---                                        |
| complexity/easy           | Easy to do                        | [search][search-complexity/easy]           |
| complexity/high           | Not so easy to do                 | [search][search-complexity/high]           |
| complexity/medium         | Relatively easy                   | [search][search-complexity/medium]         |
| kind/bug                  | Bug                               | [search][search-kind/bug]                  |
| kind/doc                  | Documentation related             | [search][search-kind/doc]                  |
| kind/enhancement          | Enhancement                       | [search][search-kind/enhancement]          |
| kind/feature              | Feature                           | [search][search-kind/feature]              |
| kind/hotfix               | Hotfix                            | [search][search-kind/hotfix]               |
| kind/infrastructure       | Infrastructure code               | [search][search-kind/infrastructure]       |
| kind/invalid              | Not valid Issue/PR                | [search][search-kind/invalid]              |
| kind/nicetohave           | Would be a nice thing             | [search][search-kind/nicetohave]           |
| kind/refactor             | Refactor codebase                 | [search][search-kind/refactor]             |
| meta/assigned             | Is assigned                       | [search][search-meta/assigned]             |
| meta/blocked              | Blocked by other Issue/PR         | [search][search-meta/blocked]              |
| meta/blocker              | Blocks other Issue/PR             | [search][search-meta/blocker]              |
| meta/decision-pending     | Not clear what to do              | [search][search-meta/decision-pending]     |
| meta/dependencies         | Dependency-related                | [search][search-meta/dependencies]         |
| meta/doc                  | Documentation related             | [search][search-meta/doc]                  |
| meta/importance/high      | Very Important                    | [search][search-meta/importance/high]      |
| meta/importance/low       | Not so important                  | [search][search-meta/importance/low]       |
| meta/importance/medium    | Rather important                  | [search][search-meta/importance/medium]    |
| meta/on-hold              | Do not work on this!              | [search][search-meta/on-hold]              |
| meta/ready                | Ready for review/merge            | [search][search-meta/ready]                |
| meta/reopen-later         | Reopen closed issue/pr later      | [search][search-meta/reopen-later]         |
| meta/WIP                  | Work in Progress                  | [search][search-meta/WIP]                  |
| nochange/duplicate        | Duplicated                        | [search][search-nochange/duplicate]        |
| nochange/question         | Question                          | [search][search-nochange/question]         |
| nochange/rfc              | Request for comments              | [search][search-nochange/rfc]              |
| nochange/wontfix          | Won't fix this issue              | [search][search-nochange/wontfix]          |
| part/bin/imag-counter     | Targets binary: imag-counter      | [search][search-part/bin/imag-counter]     |
| part/bin/imag-link        | Targets binary: imag-link         | [search][search-part/bin/imag-link]        |
| part/bin/imag-store       | Targets binary: imag-store        | [search][search-part/bin/imag-store]       |
| part/bin/imag-tag         | Targets binary: imag-tag          | [search][search-part/bin/imag-tag]         |
| part/bin/imag-view        | Targets binary: imag-view         | [search][search-part/bin/imag-view]        |
| part/interface            | Changes the interface             | [search][search-part/interface]            |
| part/lib/imagcounter      | Targets library: imagcounter      | [search][search-part/lib/imagcounter]      |
| part/lib/imagentryfilter  | Targets library: imagentryfilter  | [search][search-part/lib/imagentryfilter]  |
| part/lib/imagentrylink    | Targets library: imagentrylink    | [search][search-part/lib/imagentrylink]    |
| part/lib/imagentrylist    | Targets library: imagentrylist    | [search][search-part/lib/imagentrylist]    |
| part/lib/imagentrymarkup  | Targets library: imagentrymarkup  | [search][search-part/lib/imagentrymarkup]  |
| part/lib/imagentryprinter | Targets library: imagentryprinter | [search][search-part/lib/imagentryprinter] |
| part/lib/imagentrytag     | Targets library: imagentrytag     | [search][search-part/lib/imagentrytag]     |
| part/lib/imagentryview    | Targets library: imagentryview    | [search][search-part/lib/imagentryview]    |
| part/lib/imagnotes        | Targets library: imagnotes        | [search][search-part/lib/imagnotes]        |
| part/lib/imagrt           | Targets library: imagrt           | [search][search-part/lib/imagrt]           |
| part/lib/imagstore        | Targets library: imagstore        | [search][search-part/lib/imagstore]        |
| part/lib/imagutil         | Targets library:                  | [search][search-part/lib/imagutil]         |
| part/_new_binary          | Introduces new binary             | [search][search-part/_new_binary]          |
| part/_new_library         | Introduces new library            | [search][search-part/_new_library]         |
| test/change               | Changes a test                    | [search][search-test/change]               |
| test/missing              | Test missing                      | [search][search-test/missing]              |
| test/new                  | New test                          | [search][search-test/new]                  |

## Developer Certificate of Origin

```
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
```

## FAQ

_to be written_

[search-complexity/easy]: https://github.com/matthiasbeyer/imag/labels/
[search-complexity/high]: https://github.com/matthiasbeyer/imag/labels/complexity%2Fhigh
[search-complexity/medium]: https://github.com/matthiasbeyer/imag/labels/complexity%2Fmedium
[search-kind/bug]: https://github.com/matthiasbeyer/imag/labels/kind%2Fbug
[search-kind/doc]: https://github.com/matthiasbeyer/imag/labels/kind%2Fdoc
[search-kind/enhancement]: https://github.com/matthiasbeyer/imag/labels/kind%2Fenhancement
[search-kind/feature]: https://github.com/matthiasbeyer/imag/labels/kind%2Ffeature
[search-kind/hotfix]: https://github.com/matthiasbeyer/imag/labels/kind%2Fhotfix
[search-kind/infrastructure]: https://github.com/matthiasbeyer/imag/labels/kind%2Finfrastructure
[search-kind/invalid]: https://github.com/matthiasbeyer/imag/labels/kind%2Finvalid
[search-kind/nicetohave]: https://github.com/matthiasbeyer/imag/labels/kind%2Fnicetohave
[search-kind/refactor]: https://github.com/matthiasbeyer/imag/labels/kind%2Frefactor
[search-meta/assigned]: https://github.com/matthiasbeyer/imag/labels/meta%2Fassigned
[search-meta/blocked]: https://github.com/matthiasbeyer/imag/labels/meta%2Fblocked
[search-meta/blocker]: https://github.com/matthiasbeyer/imag/labels/meta%2Fblocker
[search-meta/decision-pending]: https://github.com/matthiasbeyer/imag/labels/meta%2Fdecision-pending
[search-meta/dependencies]: https://github.com/matthiasbeyer/imag/labels/meta%2Fdependencies
[search-meta/doc]: https://github.com/matthiasbeyer/imag/labels/meta%2Fdoc
[search-meta/importance/high]: https://github.com/matthiasbeyer/imag/labels/meta%2Fimportance%2Fhigh
[search-meta/importance/low]: https://github.com/matthiasbeyer/imag/labels/meta%2Fimportance%2Flow
[search-meta/importance/medium]: https://github.com/matthiasbeyer/imag/labels/meta%2Fimportance%2Fmedium
[search-meta/on-hold]: https://github.com/matthiasbeyer/imag/labels/meta%2Fon-hold
[search-meta/ready]: https://github.com/matthiasbeyer/imag/labels/meta%2Fready
[search-meta/reopen-later]: https://github.com/matthiasbeyer/imag/labels/meta%2Freopen-later
[search-meta/WIP]: https://github.com/matthiasbeyer/imag/labels/meta%2FWIP
[search-nochange/duplicate]: https://github.com/matthiasbeyer/imag/labels/nochange%2Fduplicate
[search-nochange/question]: https://github.com/matthiasbeyer/imag/labels/nochange%2Fquestion
[search-nochange/rfc]: https://github.com/matthiasbeyer/imag/labels/nochange%2Frfc
[search-nochange/wontfix]: https://github.com/matthiasbeyer/imag/labels/nochange%2Fwontfix
[search-part/bin/imag-counter]: https://github.com/matthiasbeyer/imag/labels/part%2Fbin%2Fimag-counter
[search-part/bin/imag-link]: https://github.com/matthiasbeyer/imag/labels/part%2Fbin%2Fimag-link
[search-part/bin/imag-store]: https://github.com/matthiasbeyer/imag/labels/part%2Fbin%2Fimag-store
[search-part/bin/imag-tag]: https://github.com/matthiasbeyer/imag/labels/part%2Fbin%2Fimag-tag
[search-part/bin/imag-view]: https://github.com/matthiasbeyer/imag/labels/part%2Fbin%2Fimag-view
[search-part/interface]: https://github.com/matthiasbeyer/imag/labels/part%2F_interface
[search-part/lib/imagcounter]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagcounter
[search-part/lib/imagentryfilter]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentryfilter
[search-part/lib/imagentrylink]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentrylink
[search-part/lib/imagentrylist]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentrylist
[search-part/lib/imagentrymarkup]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentrymarkup
[search-part/lib/imagentryprinter]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentryprinter
[search-part/lib/imagentrytag]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentrytag
[search-part/lib/imagentryview]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagentryview
[search-part/lib/imagnotes]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagnotes
[search-part/lib/imagrt]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagrt
[search-part/lib/imagstore]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagstore
[search-part/lib/imagutil]: https://github.com/matthiasbeyer/imag/labels/part%2Flib%2Fimagutil
[search-part/_new_binary]: https://github.com/matthiasbeyer/imag/labels/part%2F_new_binary
[search-part/_new_library]: https://github.com/matthiasbeyer/imag/labels/part%2F_new_library
[search-test/change]: https://github.com/matthiasbeyer/imag/labels/test%2Fchange
[search-test/missing]: https://github.com/matthiasbeyer/imag/labels/test%2Fmissing
[search-test/new]: https://github.com/matthiasbeyer/imag/labels/test%2Fnew