Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: ad32bf25db
Fetching contributors…

Cannot retrieve contributors at this time

141 lines (109 sloc) 5.21 kb
========================
Hacking on Geany-Plugins
========================
.. contents::
General
=======
About this file
---------------
This file contains some useful information for any plugin developer, and
especially for new plugin developers. A lot of information inside
`Geany's HACKING file <http://geany.org/manual/hacking.html>` is useful
as well, so it's recommended you give it a read.
Building your plugin
--------------------
You should first read either `README` or `README.waf` depending on whether
you want to use Autotools or Waf to build the plugins.
Autotools Build System
^^^^^^^^^^^^^^^^^^^^^^
The Autotools build system automatically enables some code checking
utilities, meant to ease tracking of common programming mistakes, or simply
to help making everyone's plugin code better.
They currently are:
* C compiler warnings (can be disabled with the ``--disable-extra-c-warnings``
configuration flag) -- this test is (obviouly) run during build;
* Static code analysis using ``cppcheck`` (can be disabled with the
``--disable-cppcheck`` configuration flag) -- this test is run during
``make check``.
These features are only here to help you writing better code: they are not
necessarily and always right -- though they try.
If you think they reports wrong problems, please file a report on the
appropriate place (either the mailing lists or the geany-plugins bug tracker).
Documentation
-------------
README
^^^^^^
Each plugin folder should contain at least a `README` file for
documentation.
Markup language
###############
The `README` is intended to be written in
`Restructured Text <http://sphinx.pocoo.org/rest.html>`_
(as this document is) and therefore should work with
``rst2html`` or similar tools. The reason for this is that this
information is used to generate the content of the
`Plugins Website <http://plugins.geany.org>`.
Recommended contents
####################
The documentation should include a detailed description on features
offered by the plugins and usage of those features. It should also
include some basic information to make it easier for users to get in
touch with the developer(s) or to find further help in case of any
issues. You can use some of the other `README` files to get a
general idea of what should be in the file, but generally it should
contain:
* author(s) of plugin and their mail addresses
* external web site (if any)
* known issues
* bug tracker
* dependencies
Committing
----------
General
^^^^^^^
* Commit one thing at a time, do small commits. Commits should be
meaningful and not too big when possible; multiple small commits are
good if there is no good reason to group them.
* Use meaningful name and email in the Author and Committer fields.
This helps knowing who did what and allows to contact the author if
there is a good reason to do so (unlikely, but can happen). Using
the email address associated with your GitHub account will allows
for better integration with the website's hyperlinking to accounts
features.
* When working on a new feature, create a new branch for it. When
merging it, use the --no-ff option to make sure a merge commit will
be created to better track what happened. However, if the feature
only took one commit you might merge it fast-forward since there is
not history to keep together.
Commit messages
^^^^^^^^^^^^^^^
Follow the standard Git formatting:
* No line should use more than about 80 characters (around 72 is best).
* The first line is the commit's summary and is followed by an empty
line. This summary should be one line and one line only, thus less
than 80 characters. This summary should not include any punctuation
unless really needed. See it as the subject of an email: keep it
concise and as precise as you can, but not tool long.
* If you're working on a specific plugin, prefix the summary line
with the lower case name of the plugin (same as the directory name)
to make it easier to know which commit affected which plugin without
having to thoroughly examine the commit diff itself. No prefix is
needed if the commit is non-plugin specific or affects only files
outside of the plugins' directories.
* Following lines are optional detailed commit information, with
paragraphs separated by blank lines. This part should be as long as
needed to describe the commit in depth, should use proper
punctuation and should include any useful information, like the
motivation for the patch and/or any valuable details the diff itself
doesn't provide or make clear. Make it as complete as you think
it makes sense, but don't include an information that is better
explained by the commit's diff.
It is OK to use ASCII formatting like bullet list using "*" or "-",
etc. if useful, but emphasis (bold, italic, underline) should be
avoided.
Example::
Ask the user if spawn fails in utils_open_browser()
Ask the user to configure a valid browser command if spawning it
fails rather than falling back to some arbitrary hardcoded defaults.
This avoid spawning an unexpected browser when the configured one is
wrong, and gives the user a chance to correctly fix the preference.
Jump to Line
Something went wrong with that request. Please try again.