Return to CONTRIBUTING.md CVS log

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

Annotation of embedaddon/pimd/CONTRIBUTING.md, revision 1.1.1.1

1.1       misho       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:   -->