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