From 7938570be2055329345eadcd67acddc74ff3be4d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 8 Dec 2022 18:01:55 +0000 Subject: [PATCH] docs: Replace HACKING with a contribution guide The HACKING file is woefully out of date. --- CONTRIBUTING.md | 262 ++++++++++++++++++++++++++++++++++++++++++++++++ HACKING | 64 ------------ 2 files changed, 262 insertions(+), 64 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 HACKING diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..8e9afc89c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,262 @@ +# Contribution guidelines + +Thank you for considering contributing to the GTK project! + +These guidelines are meant for new contributors, regardless of their level +of proficiency; following them allows the maintainers of the GTK project to +more effectively evaluate your contribution, and provide prompt feedback to +you. Additionally, by following these guidelines you clearly communicate +that you respect the time and effort that the people developing GTK put into +managing the project. + +GTK is a complex free software GUI toolkit, and it would not exist without +contributions from the free and open source software community. There are +many things that we value: + + - bug reporting and fixing + - documentation and examples + - tests + - new features + +Please, do not use the issue tracker for support questions. If you have +questions on how to use GTK effectively, you can use: + + - the `#gtk` IRC channel on irc.gnome.org + - the [gtk tag on the GNOME Discourse instance](https://discourse.gnome.org/tag/gtk) + +You can also look at the GTK tag on [Stack +Overflow](https://stackoverflow.com/questions/tagged/gtk). + +The issue tracker is meant to be used for actionable issues only. + +## How to report bugs + +### Security issues + +You should not open a new issue for security related questions. + +When in doubt, send an email to the [security](mailto:security@gnome.org) +mailing list. + +### Bug reports + +If you're reporting a bug make sure to list: + + 0. which version of GTK are you using? + 0. which operating system are you using? + 0. the necessary steps to reproduce the issue + 0. the expected outcome + 0. a description of the behavior; screenshots are also welcome + 0. a small, self-contained example exhibiting the behavior; if this + is not available, try reproducing the issue using the GTK examples + or interactive tests + +If the issue includes a crash, you should also include: + + 0. the eventual warnings printed on the terminal + 0. a backtrace, obtained with tools such as GDB or LLDB + +It is fine to include screenshots of screen recordings to demonstrate +an issue that is best to understand visually, but please don't just +dump screen recordings without further details into issues. It is +essential that the problem is described in enough detail to reproduce +it without watching a video. + +For small issues, such as: + + - spelling/grammar fixes in the documentation + - typo correction + - comment clean ups + - changes to metadata files (CI, `.gitignore`) + - build system changes + - source tree clean ups and reorganizations + +You should directly open a merge request instead of filing a new issue. + +### Features and enhancements + +Feature discussion can be open ended and require high bandwidth channels; if +you are proposing a new feature on the issue tracker, make sure to make +an actionable proposal, and list: + + 0. what you're trying to achieve + 0. prior art, in other toolkits or applications + 0. design and theming changes + +If you're proposing the integration of new features it helps to have +multiple applications using shared or similar code, especially if they have +iterated over it various times. + +Each feature should also come fully documented, and with tests. + +## Your first contribution + +### Prerequisites + +If you want to contribute to the GTK project, you will need to have the +development tools appropriate for your operating system, including: + + - Python 3.x + - Meson + - Ninja + - Gettext (19.7 or newer) + - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements) + +Up-to-date instructions about developing GNOME applications and libraries +can be found on [the GNOME Developer Center](https://developer.gnome.org). + +The GTK project uses GitLab for code hosting and for tracking issues. More +information about using GitLab can be found [on the GNOME +wiki](https://wiki.gnome.org/GitLab). + +### Dependencies + +In order to get GTK from Git installed on your system, you need to have the +required versions of all the software dependencies required by GTK; typically, +this means a recent version of GLib, Cairo, Pango, and ATK, as well as the +platform-specific dependencies for the windowing system you are using (Wayland, +X11, Windows, or macOS). + +The core dependencies for GTK are: + + - [GLib, GObject, and GIO](https://gitlab.gnome.org/GNOME/glib) + - [Cairo](http://cairographics.org) + - [Pango](https://gitlab.gnome.org/GNOME/pango) + - [GdkPixbuf](https://gitlab.gnome.org/GNOME/gdk-pixbuf) + - [Epoxy](https://github.com/anholt/libepoxy) + - [ATK](https://gitlab.gnome.org/GNOME/atk) + - [Graphene](https://github.com/ebassi/graphene) + +GTK will attempt to download and build some of these dependencies if it +cannot find them on your system. + +Additionally, you may want to look at projects that create a development +environment for you, like [jhbuild](https://wiki.gnome.org/HowDoI/Jhbuild) +and [gvsbuild](https://github.com/wingtk/gvsbuild). + +### Getting started + +You should start by forking the GTK repository from the GitLab web UI, and +cloning from your fork: + +```sh +$ git clone --branch=gtk-3-24 https://gitlab.gnome.org/yourusername/gtk.git gtk-3 +$ cd gtk-3 +``` + +**Note**: if you plan to push changes to back to the main repository and +have a GNOME account, you can skip the fork, and use the following instead: + +```sh +$ git clone --branch=gtk-3-24 git@gitlab.gnome.org:GNOME/gtk.git gtk-3 +$ cd gtk-3 +``` + +To compile the Git version of GTK on your system, you will need to +configure your build using Meson: + +```sh +$ meson setup _builddir . +$ meson compile -C _builddir +``` + +Typically, you should work on your own branch: + +```sh +$ git switch -C your-branch +``` + +Once you've finished working on the bug fix or feature, push the branch +to the Git repository and open a new merge request, to let the GTK +maintainers review your contribution. + +### Code reviews + +Each contribution is reviewed by the core developers of the GTK project. + +### Commit messages + +The expected format for git commit messages is as follows: + +```plain +Short explanation of the commit + +Longer explanation explaining exactly what's changed, whether any +external or private interfaces changed, what bugs were fixed (with bug +tracker reference if applicable) and so forth. Be concise but not too +brief. + +Closes #1234 +``` + + - Always add a brief description of the commit to the _first_ line of + the commit and terminate by two newlines (it will work without the + second newline, but that is not nice for the interfaces). + + - First line (the brief description) must only be one sentence and + should start with a capital letter unless it starts with a lowercase + symbol or identifier. Don't use a trailing period either. Don't exceed + 72 characters. + + - The main description (the body) is normal prose and should use normal + punctuation and capital letters where appropriate. Consider the commit + message as an email sent to the developers (or yourself, six months + down the line) detailing **why** you changed something. There's no need + to specify the **how**: the changes can be inlined. + + - When committing code on behalf of others use the `--author` option, e.g. + `git commit -a --author "Joe Coder "` and `--signoff`. + + - If your commit is addressing an issue, use the + [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html) + to automatically close the issue when merging the commit with the upstream + repository: + +```plain +Closes #1234 +Fixes #1234 +Closes: https://gitlab.gnome.org/GNOME/gtk/issues/1234 +``` + + - If you have a merge request with multiple commits and none of them + completely fixes an issue, you should add a reference to the issue in + the commit message, e.g. `Bug: #1234`, and use the automatic issue + closing syntax in the description of the merge request. + +### Commit access to the GTK repository + +GTK is part of the GNOME infrastructure. At the current time, any +person with write access to the GNOME repository can merge changes to +GTK. This is a good thing, in that it encourages many people to work +on GTK, and progress can be made quickly. However, GTK is a fairly +large and complicated project on which many other things depend, so to +avoid unnecessary breakage, and to take advantage of the knowledge +about GTK that has been built up over the years, we'd like to ask +people committing to GTK to follow a few rules: + +0. Ask first. If your changes are major, or could possibly break existing + code, you should always ask. If your change is minor and you've been + working on GTK for a while it probably isn't necessary to ask. But when + in doubt, ask. Even if your change is correct, somebody may know a + better way to do things. If you are making changes to GTK, you should + be subscribed to the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) + mailing list; this is a good place to ask about intended changes. + The `#gtk` IRC channel on irc.gnome.org is also a good place to find GTK + developers to discuss changes, but if you live outside of the EU/US time + zones, an email to the gtk-devel mailing list is the most certain and + preferred method. + +0. Ask _first_. + +0. Always write a meaningful commit message. Changes without a sufficient + commit message will be reverted. + +0. Never push to the `main` branch, or any stable branches, directly; you + should always go through a merge request, to ensure that the code is + tested on the CI infrastructure at the very least. A merge request is + also the proper place to get a comprehensive code review from the core + developers of GTK. + +If you have been contributing to GTK for a while and you don't have commit +access to the repository, you may ask to obtain it following the [GNOME account +process](https://wiki.gnome.org/AccountsTeam/NewAccounts). diff --git a/HACKING b/HACKING deleted file mode 100644 index 4b20c6b895..0000000000 --- a/HACKING +++ /dev/null @@ -1,64 +0,0 @@ -If you want to hack on the GTK+ project, you'll need to have -the following packages installed: - - - GNU autoconf 2.62 - - GNU automake 1.11 - - GNU libtool 2.2 - - indent (GNU indent 1.9.1 is known good) - - GNU gettext 10.40 - -These should be available by ftp from ftp.gnu.org or any of the -fine GNU mirrors. Beta software can be found at alpha.gnu.org. - -Up-to-date instructions about developing GNOME applications and libraries -can be found here: - - http://library.gnome.org/devel/ - -Information about using git with GNOME can be found here: - - https://wiki.gnome.org/Git - -In order to get GIT GTK+ installed on your system, you need to have -the most recent GIT versions of GLib, Pango, and ATK installed as well. -The installation process of these libraries is similar to that of GTK+, -but needs to be fulfilled prior to installation of GTK+. - -If at all possible, please use GIT to get the latest development version of -gtk+ and glib. You can do the following to get glib and gtk+ from GIT: - - $ git clone git://git.gnome.org/glib - $ git clone git://git.gnome.org/pango - $ git clone git://git.gnome.org/atk - $ git clone git://git.gnome.org/gtk+ - -Note: if you plan to push changes to back to the master repository and -have a gnome account, you want to use the following instead: - - $ git clone ssh://@git.gnome.org/git/gtk+ - -To compile the GIT version of GTK+ on your system, you will need to take -several steps to setup the tree for compilation. You can do all these -steps at once by running: - - gtk+$ ./autogen.sh - -Basically this does the following for you: - - gtk+$ aclocal; automake; autoconf - -The above commands create the `configure' script. Now you -run the `configure' script in `gtk+/' to create all Makefiles. -More information about that in `INSTALL'. - -Before running `autogen.sh' or `configure', make sure you have libtool -in your path. - -Note that autogen.sh runs configure for you. If you wish to pass -options like `--prefix=/usr' to `configure' you can give those options -to `autogen.sh' and they will be passed on to `configure'. - -For information about submitting patches and pushing changes -to GIT, see the `README' and `README.commits' files. In particular, -don't, under any circumstances, push anything to GIT before -reading and understanding `README.commmits'.