diff options
| -rw-r--r-- | CONTRIBUTING.md | 90 | ||||
| -rw-r--r-- | README.commits.md | 71 |
2 files changed, 84 insertions, 77 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3326f99043..837a61be83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Windows, or macOS). You should start by forking the GTK repository from the GitLab web UI, and cloning from your fork: -```ssh +```sh $ git clone https://gitlab.gnome.org/yourusername/gtk.git $ cd gtk ``` @@ -47,11 +47,6 @@ $ cd _builddir $ ninja ``` -**Note**: For information about submitting patches and pushing changes -to Git, see the [README.md](./README.md) and [README.commits.md](./README.commits.md) files. In particular, -don't, under any circumstances, push anything to Git before reading and -understanding [README.commits.md](./README.commits.md). - Typically, you should work on your own branch: ```sh @@ -63,3 +58,86 @@ to the Git repository and open a new merge request, to let the GTK maintainers review your contribution. The [CODE-OWNERS](./docs/CODE-OWNERS) document contains the list of core contributors to GTK and the areas for which they are responsible. + +### 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. +``` + + - 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 to + automatically close the issue on push: + +```plain +Closes #1234 +``` + + or: + +```plain +Fixes #1234 +``` + + or: + +```plain +Closes https://gitlab.gnome.org/GNOME/gtk/issues/1234 +``` + +### 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 make 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 package that many other things depend on, 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 [gtk-devel-list](https://mail.gnome.org/mailman/listinfo/gtk-devel-list). + This is a good place to ask about intended changes. + `#gtk+` on GIMPNet (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, email to gtk-devel-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 master 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. diff --git a/README.commits.md b/README.commits.md deleted file mode 100644 index c5354b64d3..0000000000 --- a/README.commits.md +++ /dev/null @@ -1,71 +0,0 @@ -GTK+ is part of the GNOME git repository. At the current time, any -person with write access to the GNOME repository, can make 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 package that many other things depend on, 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 gtk-devel-list@gnome.org. (Subscription address: - gtk-devel-list-request@gnome.org.) This is a good place to ask - about intended changes. - #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. - -0. Ask _first_. - -0. With git, we no longer maintain a ChangeLog file, but 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. - -Notes: - -* When developing larger features or complicated bug fixes, it is - advisable to work in a branch in your own cloned GTK+ repository. - You may even consider making your repository publically available - so that others can easily test and review your changes. - -* The expected format for git commit messages is as follows: - -``` -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. -``` - - - 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. Normally, for patches - sent to a mailing list it's copied from there. - - - When committing code on behalf of others use the `--author` option, e.g. - `git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`. - - -Owen Taylor -13 Aug 1998 -17 Apr 2001 - -Matthias Clasen -31 Mar 2009 - |