misc: improve README and add a CONTRIBUTING file
Change-Id: I95b604a38b211826269a571a0089dc32c044f130
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..5bd55eb
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# Contributing to Ring Gnome
+
+GNU Ring welcomes contribution from everyone. Here are some ideas if you want
+to help:
+
+## Packaging
+
+Packaging Ring allows easier installation by end-users and in this sense it's an
+excellent way of contributing to Ring!
+
+If your distribution doesn't have a Ring package you can create one, and if
+somebody is already maintaining a Ring package for your distribution,
+you can help him out!
+
+## Design
+
+Ring aims to be a universal platform of communication, accessible and usable by
+everybody. If you find issues with the client, or simply want to suggest
+improvement ideas, the bug tracker is the perfect place to submit them.
+
+## Documentation
+
+The documentation should be as up-to-date as possible to help users, devs and
+anyone who wants to get informations. This wiki is currently located [here](https://git.ring.cx/savoirfairelinux/ring-project/wikis/home).
+
+## Testing
+
+The client is under continuous development with new features, bugfixes, etc.
+Because communications software depends on a lot of conditions, we need people
+to test and fill tickets when necessary. To submit a new bug, go to https://git.ring.cx/savoirfairelinux/ring-client-gnome/issues.
+
+Sometimes interpreting bug reports is difficult for us, for example because we
+can't reproduce the bug or understand what exactly the issue is.
+This is usually because the bug report lacks of details / is too vague.
+
+In order to make your bug report as helpful as possible, think about providing
+as many details, clear explanations and scenarios as possible!
+Also, we've written a [guide on how to report bugs](https://git.ring.cx/savoirfairelinux/ring-project/wikis/Bug-report-guide),
+if you're unsure, check it out!
+
+## Support
+
+Helping users when they post issues or questions on a social network or IRC for example is appreciated. Thank you!
+
+## Communication
+
+Talk to Ring to other people is appreciated too!
+
+## Translation
+
+We are currently using [Transifex](https://www.transifex.com/savoirfairelinux/ring/) to translate the client.
+
+## Development
+
+Finally and not the least, you can also try to develop new features for this client.
+The best way is to communicate with current developers via the Contact section (see below)
+or by filling a new issue [here](https://git.ring.cx/savoirfairelinux/ring-client-gnome/issues)
+or by taking one. See the [`good-first-bug` label](https://git.ring.cx/savoirfairelinux/ring-client-gnome/issues?label_name%5B%5D=good+first+bug)
+if you don't know where to start.
+
+# Contact
+
+contributors and users frequent:
++ the `#ring` channel on `irc.freenode.net`
++ the mailing list: `ring@gnu.org`
diff --git a/README b/README.md
similarity index 60%
rename from README
rename to README.md
index 488b7d9..3250e0e 100644
--- a/README
+++ b/README.md
@@ -1,5 +1,6 @@
-ring-client-gnome
-*****************
+# Ring client Gnome
+
+[](https://jenkins.ring.cx/job/client-gnome/)
Ring-client-gnome is a Ring client written in GTK+3. It uses libRingClient to
communicate with the Ring daemon and for all of the underlying models and their
@@ -8,13 +9,14 @@
Packages for Debian/Ubuntu/Fedora can be found at https://ring.cx
-More info about the Ring project and the clients can be found on our Tuleap
-website:
- - https://tuleap.ring.cx/projects/ring/
+More info about the Ring project and the clients can be found on our Gitlab's instance:
+https://git.ring.cx/
+GNU Ring welcomes contribution from everyone. See [CONTRIBUTING.md](CONTRIBUTING.md) for help getting started.
-Requirements
-==================
+# Setting up your environment
+
+## Requirements
- Ring daemon
- libRingClient
@@ -27,62 +29,64 @@
- gettext (optional to compile translations)
On Debian/Ubuntu these can be installed by:
- sudo apt-get install g++ cmake libgtk-3-dev qtbase5-dev libclutter-gtk-1.0-dev gnome-icon-theme-symbolic libebook1.2-dev libnotify-dev gettext
+```bash
+sudo apt-get install g++ cmake libgtk-3-dev qtbase5-dev libclutter-gtk-1.0-dev gnome-icon-theme-symbolic libebook1.2-dev libnotify-dev gettext
+```
On Fedora:
- sudo dnf install gcc-c++ cmake gtk3-devel qt5-qtbase-devel clutter-gtk-devel gnome-icon-theme-symbolic evolution-data-server-devel libnotify-devel gettext
+```bash
+sudo dnf install gcc-c++ cmake gtk3-devel qt5-qtbase-devel clutter-gtk-devel gnome-icon-theme-symbolic evolution-data-server-devel libnotify-devel gettext
+```
The build instructions for the daemon and libRingClient can be found in their
respective repositories. See Gerrit:
- https://gerrit-ring.savoirfairelinux.com/#/admin/projects/
-Compiling
-==================
+## Compiling
In the project root dir:
- mkdir build
- cd build
- cmake ..
- make
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
-You can then simply run ./gnome-ring from the build directory
+You can then simply run `./gnome-ring` from the build directory
-Installing
-==================
+## Installing
If you're building the client for use (rather than testing of packaging), it is
-recommended that you install it on your system, eg: in '/usr', '/usr/local', or
-'/opt', depending on your distro's preference to get full functionality such as
+recommended that you install it on your system, eg: in `/usr`, `/usr/local`, or
+`/opt`, depending on your distro's preference to get full functionality such as
desktop integration. In this case you should perform a 'make install' after
building the client.
-Building without installing Ring daemon and libRingClient
-==================
+## Building without installing Ring daemon and libRingClient
It is possible to build ring-client-gnome without installing the daemon and
-libRingClient on your system (eg: in /usr or /usr/local):
+libRingClient on your system (eg: in `/usr` or `/usr/local`):
1. build the daemon
2. when building libRingClient, specify the location of the daemon lib in the
cmake options with -DRING_BUILD_DIR=, eg:
- -DRING_BUILD_DIR=/home/user/ring/daemon/src
+ `-DRING_BUILD_DIR=/home/user/ring/daemon/src`
3. to get the proper headers, we still need to 'make install' libRingClient, but
we don't have to install it in /usr, so just specify another location for the
install prefix in the cmake options, eg:
- -DCMAKE_INSTALL_PREFIX=/home/user/ringinstall
+ `-DCMAKE_INSTALL_PREFIX=/home/user/ringinstall`
4. now compile libRingClient and do 'make install', everything will be installed
in the directory specified by the prefix
4. now we just have to point the client to the libRingClient cmake module during
the configuration:
- -DLibRingClient_DIR=/home/user/ringinstall/lib/cmake/LibRingClient
+ `-DLibRingClient_DIR=/home/user/ringinstall/lib/cmake/LibRingClient`
-Debugging
-==================
+## Debugging
For now, the build type of the client is "Debug" by default, however it is
useful to also have the debug symbols of libRingClient. To do this, specify this
-when compiling libRingClient with '-DCMAKE_BUILD_TYPE=Debug' in the cmake
+when compiling libRingClient with `-DCMAKE_BUILD_TYPE=Debug` in the cmake
options.