forked from geany/geany-plugins
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
159 lines (123 loc) · 5.83 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
========================
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. However
it's highly recommended to make usage of them and fix maybe occuring
issues before submitting a patch. 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.
Coding and Plugin structure
===========================
I18n/l10n
---------
Geany-Plugins is supporting localisation of your plugin. To make
usage of it, there needs to be done:
* Mark each string which should be translatable with the gettext macro
``_()`` or ``N_()`` for static strings. As an example the string
``"Hello World"`` might become ``_("Hello World")``.
* Add files with translateable strings into ``po/POTFILES.in``. You
should group them for your plugin as done for the other. Each files
needs to be put into one line with complete relative path from
plugin root directory. E.g. ``myplugin/src/myplugin.c``