Debian Codegraph @

doc/HACKING

raw
1 # HACKING -*- org -*-
2 #+TITLE: Hacking notes for GPGME++
3 #+STARTUP: showall
4
5 * How to contribute
6 ** No more ChangeLog files
7
8 Do not modify any of the ChangeLog files in GPGME++. We put change
9 information only in the GIT commit log, and generate a top-level
10 ChangeLog file from logs at "make dist" time. As such, there are
11 strict requirements on the form of the commit log messages.
12
13
14 ** Commit log requirements
15
16 Your commit log should always start with a one-line summary, the
17 second line should be blank, and the remaining lines are usually
18 ChangeLog-style entries for all affected files. However, it's fine
19 -- even recommended -- to write a few lines of prose describing the
20 change, when the summary and ChangeLog entries don't give enough of
21 the big picture. Omit the leading TABs that you're used to seeing
22 in a "real" ChangeLog file, but keep the maximum line length at 72
23 or smaller, so that the generated ChangeLog lines, each with its
24 leading TAB, will not exceed 80 columns. If you want to add text
25 which shall not be copied to the ChangeLog, separate it by a line
26 consisting of two dashes at the begin of a line.
27
28 Note that ./autogen.sh installs a git hook to do some basic syntax
29 checking on the commit log message.
30
31 Typo fixes and documentation updates don't need a ChangeLog entry;
32 thus you would use a commit message like
33
34 #+begin_example
35 Fix typo in a comment
36
37 --
38 #+end_example
39
40 The marker line here is important; without it the first line would
41 appear in the ChangeLog.
42
43 If you exceptionally need to have longer lines in a commit log you may
44 do this after this scissor line:
45 #+begin_example
46 # ------------------------ >8 ------------------------
47 #+end_example
48 (hash, blank, 24 dashes, blank, scissor, blank, 24 dashes).
49 Note that such a comment will be removed if the git commit option
50 =--cleanup-scissor= is used.
51
52 ** License policy
53
54 GPGME++ is currently licensed under the LGPLv2.0+ with some tests
55 being under the GPLv2(only). We may eventually update to a newer
56 version of the licenses or a combination of them. It is thus
57 important, that all contributed code allows for an update of the
58 license; for example we can't accept code under the LGPLv2(only).
59
60 If you want to contribute code or documentation to GPGME++ you are
61 asked to assert that the contribution is in accordance to the "GPGME++
62 Developer's Certificate of Origin" as found in the file "DCO".
63 Except for a slight wording change, this DCO is identical to the one
64 used by the Linux kernel. Please take these simple steps:
65
66 - Decide which mail address you want to use. Please have your real
67 name in the address and not a pseudonym. Anonymous contributions
68 can only be done if you find a proxy who certifies for you.
69
70 - If your employer or school might claim ownership of code written
71 by you; you need to talk to them to make sure that you have the
72 right to contribute under the DCO.
73
74 - Send an OpenPGP signed mail to the [email protected] public
75 mailing list from your mail address. Include a copy of the DCO as
76 found in the official master branch. Insert your name and email
77 address into the DCO in the same way you want to use it later.
78 Example:
79
80 Signed-off-by: Joe R. Hacker <[email protected]>
81
82 If you need it, you may perform simple transformations on the mail
83 address: Replacing "@" by " at " or "." by " dot ".)
84
85 - That's it. From now on you only need to add a "Signed-off-by:"
86 line with your name and mail address to the GIT commit message.
87 It is recommended to send the patches using a PGP/MIME signed
88 mail.
89
90 ** Coding standards
91
92 Please follow the KDE Coding styles. See:
93 https://community.kde.org/Policies/Frameworks_Coding_Style
94 If you are in doubt consult the existing code as an example. Do no
95 re-indent code without a need. If you really need to do it, use a
96 separate commit for such a change.
97
98 ** Commit log keywords
99
100 - GnuPG-bug-id :: Values are comma or space delimited bug numbers
101 from bug.gnupg.org pertaining to this commit.
102 - Debian-bug-id :: Same as above but from the Debian bug tracker.
103 - CVE-id :: CVE id number pertaining to this commit.
104 - Regression-due-to :: Commit id of the regression fixed by this commit.
105 - Fixes-commit :: Commit id this commit fixes.
106 - Reported-by :: Value is a name or mail address of a bug reporter.
107 - Suggested-by :: Value is a name or mail address of someone how
108 suggested this change.
109 - Co-authored-by :: Name or mail address of a co-author
110 - Some-comments-by :: Name or mail address of the author of
111 additional comments (commit log or code).
112 - Proofread-by :: Sometimes used by translation commits.
113 - Signed-off-by :: Name or mail address of the developer
114
115 * Debug hints
116
117 - The environment variable GPGMEPP_INTERACTOR_DEBUG enables debugging
118 of the EditInteractor classes. Allowed values are `stdout`, `stderr`,
119 or a file path.
120 - The environment variable GPGME_DEBUG enables debugging of gpgme;
121 see gpgme's debug.[ch] for details.