How to contribute to Devhelp
============================
Devhelp is hosted on the GNOME GitLab instance, you can fork the repository and
then do a merge request:
https://gitlab.gnome.org/GNOME/devhelp
Read the following wiki page to know the conventions for the commit messages:
https://wiki.gnome.org/Git/CommitMessages
Devhelp philosophy
------------------
The tool is generic and can be used by other development communities, as long
as the API documentation is available in HTML and a *.devhelp2 index file is
generated. It's important to keep the door open to other development
communities, to increase diversity, and maybe bring more funding to develop
developer tools.
If you want to make the Devhelp application GNOME-specific, for example to have
a start page specific to GNOME libraries, or to download API references from
gnome.org, read the next paragraph.
Sébastien Wilmet has done a lot of refactorings to the code, to follow the
“as a library” philosophy, like for the LLVM project [1]. Almost all the code
is written as a flexible library. With a DAG (Directed Acyclic Graph) of
classes for the containment hierarchy. With the goal to create a software
product line [2] for Devhelp: keep the Devhelp application generic, and create
a new application specific to GNOME, with both applications having a really
small codebase (the GNOME-specific features would be written as a configurable
library as well). For more information see also [3].
[1] “a corpus of functionality built as a set of libraries that can be sliced
and remixed in different ways per the needs of different use-cases”
(Chris Lattner, original co-author of LLVM),
http://lists.llvm.org/pipermail/llvm-dev/2019-June/133274.html
[2] https://www.amazon.com/Feature-Oriented-Software-Product-Lines-Implementation/dp/3642375200/
[3] https://swilmet.be/blog/2019/08/18/10-years-later/
Source code locations
---------------------
The library (libdevhelp) is in the `devhelp/` directory so that an `#include`
like the following works when compiling the code:\
`#include <devhelp/[…].h>`
The application is in `src/`. (Not `src-app/` or something like it). Rationale:
it is planned to split the Git repository in two in the future, to separate the
library from the application. When there will only be the application in a git
repository, `src/` is the usual name. And historically all the source code (lib
and app) was in `src/`.
C code conventions
------------------
Devhelp follows the Linux kernel coding style, with some exceptions:
- Indentation: 8 spaces, not tabs.
- One space before *each* opening parenthesis.
- Multi-line comments must be like this:
/* First line.
* Second line.
*/
GObject classes must not be created with a G_DECLARE macro, it causes more
problems than it solves:
https://blogs.gnome.org/swilmet/2015/10/10/changing-quickly-between-a-final-and-derivable-gobject-class/
g_auto macros are not used, because:
1. It makes debugging more difficult in case of a memory handling problem.
2. It breaks the uniformity of memory handling in C. Uniformity is an important
principle for programming language design, as explained in the book
“The Psychology of Computer Programming”:
https://www.amazon.com/Psychology-Computer-Programming-Silver-Anniversary/dp/0932633420/
3. The developer needs to be very careful when using g_auto in certain
circumstances:
https://blog.fishsoup.net/2015/11/05/attributecleanup-mixed-declarations-and-code-and-goto/
See also:
https://developer.gnome.org/programming-guidelines/unstable/
Flatpak
-------
The Devhelp maintainers maintain both the nightly and the stable versions of
the Devhelp Flatpak.
The nightly version is in flatpak/ and the gnome-apps-nightly module:
https://gitlab.gnome.org/GNOME/gnome-apps-nightly
The stable version is on Flathub:
https://github.com/flathub/org.gnome.Devhelp