Return to CONTRIBUTING.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd

pimd 2.3.2

    1: Contributing to pimd
    2: ====================
    3: 
    4: pimd is an old project.  As such it has a lot of history that sometimes
    5: creep up through the cracks.  Bugs!
    6: 
    7: Bugs can be missing or unclear documentation, faulty legacy behavior,
    8: missing key features or support for a new cool operating system.  Or
    9: simple things, like speling errors or too frequent, or missing logs.
   10: 
   11: pimd exists on [GitHub][github] for this exact purpose -- to fix bugs,
   12: collaboratively.
   13: 
   14: We welcome any and all help in the form of bug reports, fixes, patches
   15: for new features -- *preferably as GitHub pull requests*, submitting a
   16: pull request practically guarantees inclusion ... other methods are of
   17: course also possible: emailing the maintainer a patch or even a raw
   18: file, or simply emailing a feature request or an alert for a problem.
   19: For email questions/requests/alerts there is always the risk of memory
   20: exhaustion on the part of the maintainer.
   21: 
   22: 
   23: Coding Style
   24: ------------
   25: 
   26: > **Tip:** Adapt your code to what the surrounding code looks like!
   27: 
   28: pimd is written in C.  C is an old language and sometimes that age is
   29: clearly visible.  The current maintainer has tried to (re)enforce a
   30: consistent and more modern C style, without having to completly
   31: re-indent the whole code base.
   32: 
   33: First of all, lines are allowed to be longer than 72 characters these
   34: days.  In fact, there exist no enforced maximum, but keeping it around
   35: 100 chars is OK.
   36: 
   37: pimd use leading four spaces in functions and structs.  The next level
   38: use eight spaces, but the original authors used tab for that level.  A
   39: `switch()` has its `case` statements indented four spaces ... but then
   40: it is more or less [KNF][].
   41: 
   42: In Emacs this coding style can be achieved by using the following
   43: footer applied to a C file:
   44: 
   45:     /**
   46:      * Local Variables:
   47:      *  version-control: t
   48:      *  indent-tabs-mode: t
   49:      *  c-file-style: "ellemtel"
   50:      *  c-basic-offset: 4
   51:      * End:
   52:      */
   53: 
   54: The current maintainer has considered shifting the original coding
   55: style to FULL [KNF][] several times.
   56: 
   57: 
   58: GIT Submodules
   59: --------------
   60: 
   61: pimd is maintained using the GIT version control system.  It also use a
   62: Git submodule, [libite][], to provide several utilities functions, like
   63: `pidfile()` and the OpenBSD `strlcpy()` family of functions.
   64: 
   65: Make sure to `git submodule update` after a `git pull`, in addition to
   66: `git submodule update --init` when you clone the repository initially.
   67: 
   68: 
   69: Commit Messages
   70: ---------------
   71: 
   72: Commit messages exist to track *why* a change was made.  Try to be as
   73: clear and concise as possible in your commit messages.  Example from
   74: the [Pro Git][gitbook] online book:
   75: 
   76:     Brief, but clear and concise summary of changes
   77:     
   78:     More detailed explanatory text, if necessary.  Wrap it to about 72
   79:     characters or so.  In some contexts, the first line is treated as
   80:     the subject of an email and the rest of the text as the body.  The
   81:     blank line separating the ummary from the body is critical (unless
   82:     you omit the body entirely); tools like rebase can get confused if
   83:     you run the two together.
   84:     
   85:     Further paragraphs come after blank lines.
   86:     
   87:      - Bullet points are okay, too
   88:     
   89:      - Typically a hyphen or asterisk is used for the bullet, preceded
   90:        by a single space, with blank lines in between, but conventions
   91:        vary here
   92: 
   93: Another good *counter* example [is this][rambling] ...
   94: 
   95: 
   96: Target Systems
   97: --------------
   98: 
   99: pimd mainly targets modern UNIX systems and we semi-regularly test it on
  100: both Debian and Ubuntu for Linux, FreeBSD, NetBSD, and OpenBSD.  Please
  101: consider these targets when submitting new features.  If you cannot test
  102: on other operating systems yourself, be prepared that your feature/fix
  103: will likely be delayed by the maintaier, who will attempt to test and in
  104: some cases port the feature for you.
  105: 
  106: 
  107: Code of Conduct
  108: ---------------
  109: 
  110: It is expected of everyone engaging in the project to, in the words of
  111: Bill & Ted; [be excellent to each other][conduct].
  112: 
  113: 
  114: [github]:   https://github.com/troglobit/pimd/
  115: [KNF]:      https://en.wikipedia.org/wiki/Kernel_Normal_Form
  116: [libite]:   https://github.com/troglobit/libite
  117: [gitbook]:  https://git-scm.com/book/ch5-2.html
  118: [rambling]: http://stopwritingramblingcommitmessages.com/
  119: [conduct]:  https://github.com/troglobit/pimd/blob/master/CODE-OF-CONDUCT.md
  120: 
  121: <!--
  122:   -- Local Variables:
  123:   -- mode: markdown
  124:   -- End:
  125:   -->