luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Rewrite CONTRIBUTING.md to update it

Browse Source 
The new version is significantly based on the proposed GTK+
CONTRIBUTING.md file
(https://gitlab.gnome.org/GNOME/gtk/merge_requests/358).

Signed-off-by: Philip Withnall <withnall@endlessm.com>
This commit is contained in:
Philip Withnall 2018-12-28 18:33:00 +00:00
parent 1afeaa6cb3
commit 91493db48b
2 changed files with 266 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
CONTRIBUTING.md
View File

@ -1,63 +1,278 @@
GLib is part of the GNOME git repository. At the current time, any
person with write access to the GNOME repository, can make changes to
GLib. This is a good thing, in that it encourages many people to work
on GLib, and progress can be made quickly. However, GLib is a fairly
large and complicated package that many other things depend on, so to
avoid unnecessary breakage, and to take advantage of the knowledge
about GLib that has been built up over the years, we'd like to ask
people committing to GLib to follow a few rules:
# Contribution guidelines
1. 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 GLib 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.
Thank you for considering contributing to the GLib project!
If you are making changes to GLib, you should be subscribed
to `gtk-devel-list@gnome.org`. (Subscription address:
`gtk-devel-list-request@gnome.org`.) This is a good place to ask
about intended changes.
These guidelines are meant for new contributors, regardless of their level
of proficiency; following them allows the core developers of the GLib 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 GLib put into
managing the project.
`#gtk+` on GIMPNet (`irc.gimp.org`, `irc.us.gimp.org`, `irc.eu.gimp.org`, …)
is also a good place to find GTK+ developers to discuss changes with,
however, email to `gtk-devel-list` is the most certain and preferred
method.
GLib is a complex free software utility library, and it would not exist without
contributions from the free and open source software community. There are
many things that we value:
2. Ask _first_.
- bug reporting and fixing
- documentation and examples
- tests
- testing and support for other platforms
- new features
3. You are expected to produce a meaningful commit message.
Changes without a sufficient commit message will be reverted. See below for
the expected format of commit messages.
Please, do not use the issue tracker for support questions. If you have
questions on how to use GLib effectively, you can use:
Notes:
- the `#gtk+` IRC channel on irc.gnome.org
- the [gtk](https://mail.gnome.org/mailman/listinfo/gtk-list) mailing list,
for general questions on GLib
- the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list)
mailing list, for questions on developing GLib itself
* When developing larger features or complicated bug fixes, it is
advisable to work in a branch in your own cloned GLib repository.
You may even consider making your repository publically available
so that others can easily test and review your changes.
You can also look at the [`glib` tag on Stack
Overflow](https://stackoverflow.com/questions/tagged/glib).
* The expected format for git commit messages is as follows:
The issue tracker is meant to be used for actionable issues only.
```
Short explanation of the commit
## How to report bugs
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.
```
### Security issues
- 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).
You should not open a new issue for security related questions.
- 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.
When in doubt, send an email to the [security](mailto:security@gnome.org)
mailing list.
- The main description (the body) is normal prose and should use normal
punctuation and capital letters where appropriate. Normally, for patches
sent to a mailing list it's copied from there.
### Bug reports
- When committing code on behalf of others use the `--author` option, e.g.
`git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`.
If you’re reporting a bug make sure to list:
0. which version of GLib 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
0. a small, self-contained example exhibiting the behavior
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
If the issue includes a memory leak, you should also include:
0. a log of definite leaks from a tool such as [valgrind’s
memcheck](http://valgrind.org/docs/manual/mc-manual.html)
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, or
- source tree clean ups and reorganizations;
or for self-contained bug fixes where you have implemented and tested a solution
already, 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 and the problem it solves
0. three (or more) existing pieces of software which would benefit from the
new feature
0. how the feature is implementable on platforms other than Linux
New APIs, in particular, should follow the ‘rule of three’, where there should
be three (or more) pieces of software which are ready to use the new APIs. This
allows us to check that the new APIs are usable in real-life code, and fit well
with related APIs. This reduces the chances of awkward or unusable APIs becoming
stable in GLib and having to be supported forever.
A common way to introduce new APIs or data types to GLib is to prototype them in
another code base for a while, to gain real-life experience with them before
they are imported into GLib and marked as stable.
Each feature should also come fully documented, and with tests which approach
full branch coverage of the new code. GLib’s CI system generates code coverage
reports which are viewable for each merge request.
If proposing a large feature or change, it’s better to discuss it (on the
`#gtk+` IRC channel or on the
[gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) mailing
list) before putting time into writing an actionable issue — and certainly
before putting time into writing a merge request.
## Your first contribution
### Prerequisites
If you want to contribute to the GLib 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 [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code
hosting and for tracking issues. More information about using GitLab can be
found [on the GNOME wiki](https://wiki.gnome.org/GitLab).
### Getting started
You should start by forking the GLib repository from the GitLab web UI, and
cloning from your fork:
```sh
$ git clone https://gitlab.gnome.org/yourusername/glib.git
$ cd glib
```
**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 git@gitlab.gnome.org:GNOME/glib.git
$ cd glib
```
To compile the Git version of GLib on your system, you will need to
configure your build using Meson:
```sh
$ meson _builddir .
$ cd _builddir
$ ninja
```
Typically, you should work on your own branch:
```sh
$ git checkout -b 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 GLib
core developers review your contribution.
### Code reviews
Each contribution is reviewed by the core developers of the GLib project.
The [CODE-OWNERS](./docs/CODE-OWNERS) document contains the list of core
contributors to GLib and the areas for which they are responsible; you
should ensure to receive their review and signoff on your changes.
It is our intention that every commit to GLib is reviewed by at least one other
person, including commits from core developers. We all make mistakes and can
always learn from each other, and code review allows that. It also reduces
[bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge
of each commit between at least two people.
With each code review, we intend to:
0. Identify if this is a desirable change or new feature. Ideally for larger
features this will have been discussed (in an issue, on IRC, or on the
mailing list) already, so that effort isn’t wasted on putting together merge
requests which will be rejected.
0. Check the design of any new API.
0. Provide realistic estimates of how long a review might take, if it can’t
happen immediately.
0. Ensure that all significant contributions of new code, or bug fixes, are
adequately tested, either through requiring tests to be submitted at the
same time, or as a follow-up.
0. Ensure that all new APIs are documented and have [introspection
annotations](https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations).
0. Check that the contribution is split into logically separate commits, each
with a good commit message.
0. Encourage further high quality contributions.
0. Ensure code style and quality is upheld.
If a code review is stalled (due to not receiving comments for two or more
weeks; or due to a technical disagreement), please ping another GLib core
developer on the merge request, or on IRC, to ask for a second opinion.
### 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 <joe@coder.org>"` 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/glib/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.
### Merge access to the GLib repository
GLib is part of the GNOME infrastructure. At the current time, any
person with write access to the GNOME repository can merge merge requests to
GLib. This is a good thing, in that it allows maintainership to be delegated
and shared as needed. However, GLib is a fairly large and complicated package
that many other things depend on, and which has platform specific behavior — so
to avoid unnecessary breakage, and to take advantage of the knowledge about GLib
that has been built up over the years, we’d like to ask people contributing to
GLib to follow a few rules:
0. Never push to the `master` 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 GLib.
0. Always get a code review, even for seemingly trivial changes.
0. Pay attention to the CI results. Merge requests cannot be merged until the
CI passes. If they consistently fail, either something is wrong with the
change, or the CI tests need fixing — in either case, please bring this to
the attention of a core developer rather than overriding the CI.
If you have been contributing to GLib 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).

2
docs/CODE-OWNERS Normal file
View File

@ -0,0 +1,2 @@
Currently, all code is maintained equally by the core maintainers.
See glib.doap for their names.