GNOME.org
 

[folks/wip/nielsdg/markdownify-readme] Convert README and HACKING to markdown

commit b0fe42927ed354dd6d6c25840986021d8893c6b7
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Fri Apr 19 08:55:29 2019 +0200

    Convert README and HACKING to markdown
    
    And update them to use Meson conventions for testing and building rather
    than autotools-related ones.

 HACKING => HACKING.md | 146 +++++++++++++++++++++++---------------------------
 README                |  12 -----
 README.md             |  51 ++++++++++++++++++
 3 files changed, 118 insertions(+), 91 deletions(-)
---
diff --git a/HACKING b/HACKING.md
similarity index 63%
rename from HACKING
rename to HACKING.md
index 15ddf73b..fa75eacb 100644
--- a/HACKING
+++ b/HACKING.md
@@ -1,39 +1,37 @@
-This file is meant to summarize the Folks development policies.
+Folks development policies
+==========================
 
 Code merging
-============
-
-This is the work flow for modifying the master repository:
+------------
+This is the work flow for modifying the folks repository:
 
 1. File a bug for the given flaw or feature (if it does not already exist) at
-   <https://gitlab.gnome.org/GNOME/folks/issues>.
+   https://gitlab.gnome.org/GNOME/folks/issues.
 
-2. Clone the main repository (if you haven't already) and start work in a new
-   branch (which preferably includes the bug number in its name).
+2. Create a fork of the main repository on gitlab.gnome.org (if you haven't
+   already) and commit your work there.
 
 3. If this is a non-trivial flaw or feature, write test cases. We won't accept
    significant changes without adequate test coverage.
 
 4. Write code to fix the flaw or add the feature. In the case that tests are
    necessary, the new tests must pass consistently.
-   
+
 5. All code must follow the project coding style (see below).
 
-6. The project must remain buildable with all configure options and pass all
-   tests on all platforms.
+6. Make a Merge Request from your fork to the main folks repository.
 
-7. Push your branch to a public repository and attach patch(es) to the bug. Ask
-   for a review.
+7. The project must remain buildable with all meson options and pass all
+   tests on all platforms. It should also pass the CI.
 
 8. Rework your code based on suggestions in the review and submit new patches.
    Return to the review step as necessary.
 
-9. Upon approval, pull the latest master branch, rebase your branch upon it, and
-   push the resulting branch to master. Simple!
+9. Finally, if everything is reviewed and approved, a maintainer will merge it
+   for you. Thanks!
 
 Clean commits
-=============
-
+-------------
 Commits/patches should be as fine-grained as possible (and no finer). Every
 distinct change should be in its own commit and every commit should be a
 meaningful change on its own.
@@ -44,14 +42,12 @@ critical that the master branch be buildable (and all tests pass) after every
 merge.
 
 Coding style
-============
-
+------------
 In general, Folks follows the Telepathy-GLib coding style described in
-<http://telepathy.freedesktop.org/wiki/Style>.
+http://telepathy.freedesktop.org/wiki/Style.
 
 Additional general rules
 ------------------------
-
 1. All public symbols which support a Valadoc comment block must have one. This
    comment block must also be sufficient for gobject-introspection to adequately
    introspect the symbol for use in other programming languages.
@@ -60,60 +56,57 @@ Additional general rules
 
 Vala-specific rules
 -------------------
-
 1. Any functions which could block must be async.
 
 2. Use the language-native Errors for error reporting, not return values.
 
-3. Take advantage of properties and their automatic notify signals as much as
+3. Take advantage of properties and their automatic `notify` signals as much as
    possible (this eliminates the need for most special accessors, mutators, and
    custom signals and is more conventional).
 
 4. Class function blocks should be indented like GNU/Telepathy-GLib if/while
    blocks. It's arguable that these should be aligned in column 0, as in regular
-   C functions, but it's too late to change this (as it would make 'git blame'
+   C functions, but it's too late to change this (as it would make `git blame`
    useless).
 
-5. Private and internal class data members should begin with a _ (public data
-   members and local variables should not begin with a _). This is to make
+5. Private and internal class data members should begin with a `_` (public data
+   members and local variables should not begin with a `_`). This is to make
    non-public data members instantly recognizable as such (which helps
    readability).
 
-6. Private and internal class functions should begin with a _ (public functions
-   should not begin with a _). This is to make non-public functions instantly
-   recognizable as such (which helps readability).
+6. Private and internal class functions should begin with a `_` (public
+   functions should not begin with a `_`). This is to make non-public functions
+   instantly recognizable as such (which helps readability).
 
-7. Maximize use of the 'var' variable type. This shortens the declarations where
+7. Maximize use of the `var` variable type. This shortens the declarations where
    it's valid, reducing noise.
 
-   Rarely, the use of 'var' can obscure the effective type of the variable. In
+   Rarely, the use of `var` can obscure the effective type of the variable. In
    this case, it's acceptable to provide an explicit type.
 
-8. Use the 'unowned' modifier when it would prevent a non-trivial amount of
+8. Use the `unowned` modifier when it would prevent a non-trivial amount of
    memory allocation. This is most commonly true for strings, arrays, and
    non-reference-counted variables.
 
-   Do not use 'unowned' for reference-counted variables (like objects) since it
+   Do not use `unowned` for reference-counted variables (like objects) since it
    reduces readability without benefit. And, as of this writing, bgo#638199
    forces unowned variables to have an explicit type (preventing the use of
-   'var').
+   `var`).
 
 9. As in most languages, avoid casting. Casting is usually a sign of an error
    which should be fixed and reduces readability.
 
 10. Refer to non-local variables and methods with their qualified name. Within a
-    class function, refer to private data members like 'this._foo' and foreign
-    package symbols like 'package_name.symbol'.
+    class function, refer to private data members like `this._foo` and foreign
+    package symbols like `package_name.symbol`.
 
     This makes scope immediately clear, helping readability.
 
 11. Use nullable types correctly. This helps readability (and makes the
-    programmer's intentions clearer about whether a variable may be null). The
+    programmer's intentions clearer about whether a variable may be `null`). The
     ultimate goal is for folks to compile correctly with Vala’s strict-non-null
     mode enabled
     (https://wiki.gnome.org/Projects/Vala/Tutorial#Strict_Non-Null_Mode).
-    You can compile folks with strict-non-null mode enabled using:
-        make VALAFLAGS=--enable-experimental-non-null
 
 12. Place the (private) member variable declaration for a variable which backs a
     property next to the (public) property declaration, rather than at the top
@@ -121,53 +114,50 @@ Vala-specific rules
     possible in one location.
 
 13. Initialise member variables when declaring them, if possible, rather than in
-    a constructor or construct{} block. If it’s not possible to initialise a
+    a constructor or `construct {}` block. If it’s not possible to initialise a
     member variable at declaration time (e.g. because its value depends on
-    another variable), perform the initialisation in a construct{} block rather
-    than a specific constructor. This means that the initialisation doesn’t have
-    to be copied between multiple alternate constructors.
+    another variable), perform the initialisation in a `construct{}` block
+    rather than a specific constructor. This means that the initialisation
+    doesn’t have to be copied between multiple alternate constructors.
 
-14. When iterating over a MultiMap, try to use the map_iterator().
-    This is more efficient than iterating over the result of get_keys(),
-    then calling get() separately for each key.
+14. When iterating over a `Gee.MultiMap`, try to use the `map_iterator()`.
+    This is more efficient than iterating over the result of `get_keys()`,
+    then calling `get()` separately for each key.
 
 Build health
-============
-
+------------
 1.  Before pushing commits to the mainline branch, the final commit in the
-    series must successfully build and pass 'make check' consistently.
+    series must successfully build and pass `meson test` consistently.
 
 2.  After commits have been pushed to mainline, all buildbots must successfully
-    build and pass 'make check' on their next build of Folks. It's up to the
+    build and pass `meson test` on their next build of Folks. It's up to the
     committer to ensure this requirement is met and make necessary changes.
 
 Debugging tests
-===============
-
-If a test ever crashes, you'll probably want to run it through gdb. The exact
-setup work for that is a bit complicated, so we've provided some convenience
-hooks for each test. Simply run:
-
-        make -C tests/<dir> <test name>.gdb
-
-Then use gdb as normal.
-
+---------------
 To run a single test:
-        make -C tests/<dir> check TESTS=<test name>
 
-Thanks to automake’s parallel test harness, the output from all tests is logged
-automatically to <test name>.log, so no additional options need to be provided
-to force verbose output.
+```
+meson test -C builddir $test_name
+```
 
-If a test needs to be run through Valgrind for memory debugging, use:
-        make -C tests/<dir> check TESTS=<test name> FOLKS_TEST_VALGRIND=1
+If a test ever crashes, you'll probably want to run it through gdb or valgrind.
+Meson provides a convenience options for these, and documents these at
+http://mesonbuild.com/Unit-tests.html. Some examples:
 
-If a test needs to be run through Callgrind for performance profiling, use:
-        make -C tests/<dir> check TESTS=<test name> FOLKS_TEST_CALLGRIND=1
+```
+meson test -C $builddir --repeat=100 $test_name
+meson test -C $builddir --gdb $test_name
+meson test -C $builddir --wrap=valgrind $test_name
+```
 
-Profiling folks
-===============
+Thanks to meson's test harness, the output from all tests is logged
+automatically to `$builddir/meson-logs/testlog.txt` and in JSON format to
+`$builddir/meson-logs/testlog.json`, so no additional options need to be
+provided to force verbose output.
 
+Profiling folks
+---------------
 Folks has various profiling points throughout its startup code, in order to be
 able to profile the startup process. In order to use this:
  1. Compile folks with --enable-profiling.
@@ -181,13 +171,12 @@ script itself can be downloaded from
 http://gitorious.org/projects/performance-scripts.
 
 Running folks from JHBuild master
-=================================
-
+---------------------------------
 When running folks from JHBuild master, problems may be caused by running it on
 an inappropriate D-Bus session bus, typically resulting in the following error:
 
-    folks-WARNING **: Failed to find primary PersonaStore with type ID 'eds' and
-        ID 'system-address-book'.
+> folks-WARNING **: Failed to find primary PersonaStore with type ID 'eds' and
+> ID 'system-address-book'.
 
 This is caused by compiling folks against git master of evolution-data-server,
 but then running it against an older version with a different API. EDS exposes
@@ -206,18 +195,17 @@ There are two ways to fix this:
    http://www.murrayc.com/permalink/2008/07/16/d-bus-in-jhbuild-confusion-and-hacks/
 
 Environment variables
-=====================
-
-FOLKS_BACKEND_STORE_KEY_FILE_PATH sets the keyfile used to control the set
-of enabled backends. The default is g_get_user_data_dir()/folks/backends.ini,
+---------------------
+`FOLKS_BACKEND_STORE_KEY_FILE_PATH` sets the keyfile used to control the set
+of enabled backends. The default is `g_get_user_data_dir()/folks/backends.ini`,
 and if it is empty, all backends are enabled.
 
-If FOLKS_BACKENDS_ALLOWED is set, it's a space-, comma- or
+If `FOLKS_BACKENDS_ALLOWED` is set, it's a space-, comma- or
 colon-separated list of backends to allow, or "all". If unset, the
 default is equivalent to "all". Backends not in the list are disallowed,
 even if enabled in the keyfile or with enable_backend().
 
-If FOLKS_BACKENDS_DISABLED is set, it's a space-, comma- or
+If `FOLKS_BACKENDS_DISABLED` is set, it's a space-, comma- or
 colon-separated list of backends to disallow, or "all". If unset, the
 default is equivalent to "all". Backends in the list are disallowed,
 even if enabled in the keyfile or with enable_backend().
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..a0208b6b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+Folks
+=====
+
+libfolks is a library that aggregates people from multiple sources (eg,
+Telepathy connection managers) to create metacontacts.
+
+## Building
+You can build and install libfolks using [Meson]:
+
+```sh
+meson build
+ninja -C build
+ninja -C build install
+```
+
+Various backends can be enabled or disabled at compile-time. A comprehensive
+list of compile-time options can be found at `meson_options.txt`
+
+## Contributing
+You can browse the code, issues and more at libfolks' [GitLab repository].
+
+If you find a bug in libfolks, please file an issue on the [issue tracker].
+Please try to add reproducible steps and the relevant version of libfolks.
+
+If you want to contribute functionality or bug fixes, please open a Merge
+Request (MR). For more info on how to do this, see GitLab's [help pages on
+MR's]. Please also follow our coding conventions, as described in HACKING.md
+
+If libfolks is not translated in your language or you believe that the current
+translation has errors, you can join one of the various translation teams in
+GNOME. Translators do not commit directly to Git, but are advised to use our
+separate translation infrastructure instead. More info can be found at the
+[translation project wiki page].
+
+## More information
+libfolks has its own web page on https://wiki.gnome.org/Projects/Folks.
+
+To discuss issues with developers and other users, you can post to the [GNOME
+discourse] instance or join [#contacts] on irc.gnome.org.
+
+## License
+libfolks is released under the LGPL, version 2.1. See `COPYING` for more info.
+
+[GNOME]: https://www.gnome.org
+[Meson]: http://mesonbuild.com
+[GitLab repository]: https://gitlab.gnome.org/GNOME/folks
+[help pages on MR's]: https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html
+[issue tracker]: https://gitlab.gnome.org/GNOME/folks/issues
+[translation project wiki page]: https://wiki.gnome.org/TranslationProject/
+[GNOME Discourse]: https://discourse.gnome.org
+[#contacts]: irc://irc.gnome.org/contacts
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]