gplugin/gplugin

Document clang-format in HACKING
develop
2020-02-15, Richard Laager
d286b22e30f0
Parents 80a193a2c6c3
Children 672c7b29b1f0
Document clang-format in HACKING

This also renames HACKING to HACKING.md, as we are using Markdown
formatting in the file.
2 files changed, 70 insertions(+), 22 deletions(-)
  • +0 -22
    HACKING
  • +70 -0
    HACKING.md
    • --- a/HACKING Fri Feb 14 17:47:12 2020 -0600
    +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
    @@ -1,22 +0,0 @@
    -GPlugin uses hgflow[1] for development. All development takes place on the
    -develop branch which leaves default to be a stable release clone. All long
    -term feature/bug fix work should take place on a feature branch that when
    -closed, gets merged to develop.
    -
    -Releases are forked from develop and create a new branch for any testing/bug
    -fixes. When a release is deemed done, it's merged back into develop and into
    -default. hgflow takes care of all of this for us.
    -
    -To add a feature please clone `https://keep.imfreedom.org/gplugin/gplugin`.
    -Once you have your fork cloned and hgflow setup and installed, type:
    -
    -```
    -hg flow feature start $NAME_OF_YOUR_FEATURE$
    -```
    -
    -This will create a new branch for you to do your work on. When your work has
    -been completed, please open a review request at
    -[reviews.imfreedom.org](https://reviews.imfreedom.org).
    -
    -[1] https://hg.sr.ht/~wu/hgflow
    -
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/HACKING.md Sat Feb 15 18:48:39 2020 -0600
    @@ -0,0 +1,70 @@
    +## clang-format
    +
    +GPlugin uses [clang-format][1] to automatically format code. Version 9 (or
    +higher) is required. Earlier versions will fail on the options in the
    +`.clang-format` file.
    +
    +You can use clang-format in one or more of the following ways:
    +* Integrate it into your editor. The [clang-format page][1] has examples.
    +* Use a Mercurial [hook script][2].
    +* Run `ninja clang-format` from your build directory.
    +* Worst case, run `clang-format -i SOME_FILE` manually.
    +
    +### GObject Functions
    +
    +GObject and GPlugin have functions which take pairs of name/value arguments:
    +* `g_object_get()`
    +* `g_object_new()`
    +* `gplugin_plugin_info_new()`
    +
    +If code calling one of these functions with such pairs has to be wrapped, the
    +pairs are easier to read and edit with manual formatting to group the name and
    +value on the same line (but otherwise following the usual formatting that
    +clang-format would apply):
    +```
    + /* clang-format off */
    + g_object_get(
    + G_OBJECT(info),
    + "name", &name,
    + "summary", &summary,
    + NULL);
    + /* clang-format on */
    +```
    +
    +### Debian
    +
    +Debian and derivatives (e.g. Ubuntu) ship clang-format version 9 in a package
    +named `clang-format-9`. The package named `clang-format` is currently an
    +older version. Additionally, the `clang-format-9` package will not place a
    +`clang-format` in the `$PATH`. Install as follows:
    +
    +```
    +sudo apt install clang-format-9
    +sudo update-alternatives --set clang-format /usr/bin/clang-format-9
    +```
    +
    +## hgflow
    +
    +GPlugin uses [hgflow][3] for development. All development takes place on the
    +develop branch which leaves default to be a stable release clone. All long
    +term feature/bug fix work should take place on a feature branch that when
    +closed, gets merged to develop.
    +
    +Releases are forked from develop and create a new branch for any testing/bug
    +fixes. When a release is deemed done, it's merged back into develop and into
    +default. hgflow takes care of all of this for us.
    +
    +To add a feature please clone `https://keep.imfreedom.org/gplugin/gplugin`.
    +Once you have your fork cloned and hgflow setup and installed, type:
    +
    +```
    +hg flow feature start $NAME_OF_YOUR_FEATURE$
    +```
    +
    +This will create a new branch for you to do your work on. When your work has
    +been completed, please open a review request at
    +[reviews.imfreedom.org](https://reviews.imfreedom.org).
    +
    +[1]: https://clang.llvm.org/docs/ClangFormat.html
    +[2]: https://hg.mozilla.org/projects/nss/file/default/coreconf/precommit.clang-format.sh
    +[3]: https://hg.sr.ht/~wu/hgflow