[gedit] contributing: refer to the GtkSourceView HACKING file
- From: Sébastien Wilmet <swilmet src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gedit] contributing: refer to the GtkSourceView HACKING file
- Date: Mon, 26 Aug 2019 09:38:16 +0000 (UTC)
commit 00ef34068705d0f96c0283620f5cd61d10d2c1ea
Author: Sébastien Wilmet <swilmet gnome org>
Date: Mon Aug 26 11:20:07 2019 +0200
contributing: refer to the GtkSourceView HACKING file
Add a link to the GtkSourceView HACKING file, and don't duplicate its
content in the gedit CONTRIBUTING file. It's a big simplification. In
the past I've synced the two files between GSV and gedit, then I've
improved the GSV HACKING file but I was no longer contributing to gedit
so the gedit file was not updated; now it's fixed.
The "Building from git" section is already explained in the
`docs/gedit-development-getting-started.md` file.
CONTRIBUTING | 206 +++--------------------------------------------------------
1 file changed, 10 insertions(+), 196 deletions(-)
---
diff --git a/CONTRIBUTING b/CONTRIBUTING
index 5e65b8360..e1d414a41 100644
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -20,202 +20,16 @@ feature requests. The gedit developers often have difficulties to triage all the
bugs and do first line support. Having a curated list of important bugs to fix
would tremendously help the gedit developers.
-Getting started with gedit software development
------------------------------------------------
+Software development
+--------------------
-See the file `docs/gedit-development-getting-started.md` and the rest of this
-file.
+To get started with gedit software development, see the file
+`docs/gedit-development-getting-started.md`.
-Source code repository
-----------------------
+gedit follows the same guidelines and code conventions as GtkSourceView. See
+the [GtkSourceView HACKING file](https://gitlab.gnome.org/GNOME/gtksourceview/blob/master/HACKING).
-gedit source code is maintained using the git version control system
-and is available at the following location:
-
- git://git.gnome.org/gedit
-
-Or if you have an account on GNOME servers:
-
- ssh://USERNAME git gnome org/git/gedit
-
-A web interface is available at:
-
- https://git.gnome.org/browse/gedit
-
-
-Building from git
------------------
-
-When building from a git checkout you will need to run the
-autogen.sh script which takes care of running automake, autoconf,
-etc and then run "configure" for you. You can pass options like
---prefix to autogen.sh and they will be forwarded to the configure
-script.
-
-Note that you cannot run gedit from its build directory: you need
-to install it with "make install". For this reason it is highly
-recommended that you install in a separate prefix instead of
-overwriting your system binaries. Note however that when running
-gedit from a custom prefix you will need to set many environment
-variables accordingly, for instance PATH and XDG_DATA_DIR.
-The JHBuild tool can take care of all this for you.
-
-
-Commit guidelines
------------------
-
-Please don't commit directly to the git repository unless
-you have been given the green light to commit freely to gedit.
-When in doubt assume you haven't ;-).
-
-Please attach patches in bugzilla (http://bugzilla.gnome.org).
-If the patch fixes a bug that is not reported yet in bugzilla or is
-an enhancement, create a new bugreport.
-
-Please create patches with the git format-patch command.
-
-If you are a translator feel free to mark strings for translation,
-fix typos in the code, etc.
-
-Please send patches for build & configure fixes too. I really appreciate
-your help, I just want to review these fixes before applying.
-
-If you are a "build sheriff", feel free to commit fixes for build and
-configure (please, send me an e-mail with the patch you have applied).
-
-When committing to the gedit git repository make sure to include a
-meaningful commit message. Changes without a sufficient commit message
-will be reverted. Commit messages should have the following format:
-
-=== begin example commit ===
-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.
-=== end example commit ===
-
- - 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.
-
-
-Code conventions
-----------------
-
-You may encounter old code that doesn't follow all the following code
-conventions, but for new code it is better to follow them, for consistency.
-
- - Avoid trailing whitespace.
-
- - Indent the C code with tabulations with a width of eight characters.
-
- - The files should have a modeline for the indentation style.
-
- - All blocks should be surrounded by curly braces, even one-line blocks. It
- spaces out the code, and it is more convenient when some code must be added
- or removed without the need to add or remove the curly braces.
-
- - Follow the C89 standard. In particular, no "//"-style comments.
-
- - As a general rule of thumb, follow the same coding style as the surrounding
- code.
-
- - Do not be cheap about blank lines, spacing the code vertically help
- readability. However never use two consecutive blank lines, there is really
- no need.
-
-
-Programming best practices
---------------------------
-
-gedit is a pretty big piece of software, developed over the years by different
-people and GNOME technologies. Some parts of the code may be a little old. So
-when editing the code, we should try to make it better, not worse.
-
-Here are some general advices.
-
- - Simplicity: the simpler code the better. Any trick that seem smart when you
- write it is going to bite your ass later when reading the code. Given that
- you spend 90% of the time staring at the code and 10% writing it, making
- reading the code harder is a net loss.
-
- - Brevity: make an effort to refactor common code into utility functions and
- use library function whenever is possible: every time you cut and paste a
- line of code you are throwing away all the precious seconds of your life
- that you will later spend trying to figure out the differences among the two
- copies that will have surely diverged.
-
- - Code for change: code is bound to contain bugs no matter how well it is
- written. A good coding style allows to fix these bugs with minimal changes
- instead of reformatting a whole section of unrelated code, this is
- especially important to make patch review easier and to easily understand
- the commit history. Some practical examples are:
-
- - Factor code into self contained functions so that changing a function
- does not require to change all the callers.
-
- - Do not align variable declaration, "case" statements etc, since this
- will inevitably mean that when a line will change you'll have to
- reformat all the surrounding ones.
-
- - Declare variables in the strictest scope as possible.
-
- - Reorder functions so that you do not need prototypes for static
- functions so that when you change them you need to change them only in
- one place.
-
- - Self documentation and code comments: use code comments parsimoniously. Code
- should be written so that it is clear and evident without the need of
- comments. Besides, comments usually get outdated when the code is changed
- and they become misleading. In particular avoid stating the obvious e.g. "a
- = 1; /* assign 1 to a */". Use good function names and variables to make the
- code self-documented.
-
- A good function name is one that explain clearly all what its code really
- does. There shouldn't be hidden features. If you can not find easily a good
- function name, you should probably split the function in smaller pieces. A
- function should do only one thing, but do it well.
-
- Please avoid lots of one-letter variables. And a variable should be used for
- only one purpose.
-
- Self-documentation is obviously not always possible, so when a comment is
- needed, it is needed. In those cases make sure to explain why and not only
- how a specific thing is done: you can deduce the "how" from the code, but
- not the "why". Public library functions should always be documented and in
- particular should include the calling conventions, e.g. if the result should
- be freed by the caller.
-
- Do not use fancy frames around comments like a line full of
- /*---------------*/ etc.
-
- - Contribute below on the stack. Fix a problem at the right place, instead of
- writing hacks to work around a bug or a lack of feature in an underlying
- library.
-
-
-See also
---------
-
-https://developer.gnome.org/programming-guidelines/stable/
-https://wiki.gnome.org/Projects/GTK%2B/BestPractices
-http://ometer.com/hacking.html
-http://blogs.gnome.org/swilmet/2012/08/01/about-code-quality-and-maintainability/
-
-
-Thanks,
-
- The gedit team.
+The gedit and gedit-plugins Git repositories are hosted on the GNOME GitLab
+instance:
+- [gedit on GitLab](https://gitlab.gnome.org/GNOME/gedit)
+- [gedit-plugins on GitLab](https://gitlab.gnome.org/GNOME/gedit-plugins)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]