Blame doc/HACKING

Packit fc043f
# HACKING                                                       -*- org -*-
Packit fc043f
#+TITLE: Various hacking notes
Packit fc043f
#+STARTUP: showall
Packit fc043f
Packit fc043f
* How to contribute
Packit fc043f
Packit fc043f
  The following stuff explains some basic procedures you need to
Packit fc043f
  follow if you want to contribute code or documentation.
Packit fc043f
Packit fc043f
* No more ChangeLog files
Packit fc043f
Packit fc043f
  Do not modify any of the ChangeLog files in Libgpg-error.  Starting
Packit fc043f
  on December 1st, 2011 we put change information only in the GIT
Packit fc043f
  commit log, and generate a top-level ChangeLog file from logs at
Packit fc043f
  "make dist" time.  As such, there are strict requirements on the
Packit fc043f
  form of the commit log messages.  The old ChangeLog files have all
Packit fc043f
  be renamed to ChangeLog-2011
Packit fc043f
Packit fc043f
Packit fc043f
* Commit log requirements
Packit fc043f
Packit fc043f
  Your commit log should always start with a one-line summary, the
Packit fc043f
  second line should be blank, and the remaining lines are usually
Packit fc043f
  ChangeLog-style entries for all affected files.  However, it's fine
Packit fc043f
  -- even recommended -- to write a few lines of prose describing the
Packit fc043f
  change, when the summary and ChangeLog entries don't give enough of
Packit fc043f
  the big picture.  Omit the leading TABs that you're used to seeing
Packit fc043f
  in a "real" ChangeLog file, but keep the maximum line length at 72
Packit fc043f
  or smaller, so that the generated ChangeLog lines, each with its
Packit fc043f
  leading TAB, will not exceed 80 columns.
Packit fc043f
Packit fc043f
* Commit log keywords
Packit fc043f
Packit fc043f
  - GnuPG-bug-id :: Values are comma or space delimited bug numbers
Packit fc043f
                    from bug.gnupg.org pertaining to this commit.
Packit fc043f
  - Debian-bug-id :: Same as above but from the Debian bug tracker.
Packit fc043f
  - CVE-id :: CVE id number pertaining to this commit.
Packit fc043f
  - Regression-due-to :: Commit id of the regression fixed by this commit.
Packit fc043f
  - Fixes-commit :: Commit id this commit fixes.
Packit fc043f
  - Reported-by :: Value is a name or mail address of a bug reporte.
Packit fc043f
  - Suggested-by :: Value is a name or mail address of someone how
Packit fc043f
                    suggested this change.
Packit fc043f
  - Co-authored-by :: Name or mail address of a co-author
Packit fc043f
  - Some-comments-by :: Name or mail address of the author of
Packit fc043f
                        additional comments (commit log or code).
Packit fc043f
  - Proofread-by :: Sometimes used by translation commits.
Packit fc043f
  - Signed-off-by :: Name or mail address of the developer
Packit fc043f
Packit fc043f
* Sending patches
Packit fc043f
Packit fc043f
  - submitting patches, and subsequent discussions around them,
Packit fc043f
    happens via the gnupg-devel@gnupg.org public mailing list
Packit fc043f
Packit fc043f
  - send your patches to that list, preferably PGP/MIME signed. Make
Packit fc043f
    sure to include a mention of 'libgpg-error' in the subject line,
Packit fc043f
    the list is used for several different projects
Packit fc043f
Packit fc043f
  - if you're working from the git repo, here's a suggested workflow:
Packit fc043f
Packit fc043f
    - configure git send-email defaults:
Packit fc043f
Packit fc043f
        git config format.subjectPrefix 'PATCH libgpg-error'
Packit fc043f
        git config sendemail.to gnupg-devel@gnupg.org
Packit fc043f
Packit fc043f
      Note that running ./autogen.sh on a fresh clone will do this for
Packit fc043f
      you.
Packit fc043f
Packit fc043f
    - hack hack hack
Packit fc043f
Packit fc043f
    - commit your changes; group changes into easily-reviewable commit
Packit fc043f
      units, feel free to submit several patches at once
Packit fc043f
Packit fc043f
    - e.g. if you want to submit a single patch on top of master, do:
Packit fc043f
      git send-email --annotate -1
Packit fc043f
Packit fc043f
    - e.g. if you have two commits on top of master, do:
Packit fc043f
      git send-email --annotate --cover-letter -2
Packit fc043f
      (that prompts you for a summary mail to precede your actual
Packit fc043f
      patch mails)
Packit fc043f
Packit fc043f
    - use --dry-run to test your setup