Commit e153d439 authored by Niels De Graef's avatar Niels De Graef

Convert README and HACKING to markdown

And update them to use Meson conventions for testing and building rather
than autotools-related ones.
parent a473413f
Pipeline #77114 passed with stage
in 9 minutes and 32 seconds
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 automakes 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().
libfolks is a library that aggregates people from multiple sources (eg,
Telepathy connection managers) to create metacontacts.
This source distribution also builds a Telepathy backend
(libfolks-telepathy-backend.so) and Telepathy-specific implementations of the
libfolks classes (libfolks-telepathy.so).
Browse the official repository for folks here:
https://gitlab.gnome.org/GNOME/folks
More information is available at:
https://wiki.gnome.org/Projects/Folks
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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment