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     ! 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:   -->