Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 160 lines (123 sloc) 5.974 kb
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
1 ========================
2 Hacking on Geany-Plugins
3 ========================
4 .. contents::
5
6 General
7 =======
8
9 About this file
10 ---------------
11 This file contains some useful information for any plugin developer, and
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bullet...
frlan authored
12 especially for new plugin developers. A lot of information inside
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
13 `Geany's HACKING file <http://geany.org/manual/hacking.html>` is useful
14 as well, so it's recommended you give it a read.
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
15
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
16
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
17 Building your plugin
18 --------------------
19 You should first read either `README` or `README.waf` depending on whether
20 you want to use Autotools or Waf to build the plugins.
21
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
22
8b2f4c6 @b4n Add a HACKING with a few information for plugin developers
b4n authored
23 Autotools Build System
24 ^^^^^^^^^^^^^^^^^^^^^^
25 The Autotools build system automatically enables some code checking
26 utilities, meant to ease tracking of common programming mistakes, or simply
27 to help making everyone's plugin code better.
28 They currently are:
29
30 * C compiler warnings (can be disabled with the ``--disable-extra-c-warnings``
31 configuration flag) -- this test is (obviouly) run during build;
32 * Static code analysis using ``cppcheck`` (can be disabled with the
33 ``--disable-cppcheck`` configuration flag) -- this test is run during
34 ``make check``.
35
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bullet...
frlan authored
36 These features are only here to help you writing better code: they
37 are not necessarily and always right -- though they try. However
38 it's highly recommended to make usage of them and fix maybe occuring
39 issues before submitting a patch. If you think they reports wrong
40 problems, please file a report on the appropriate place (either the
41 mailing lists or the geany-plugins bug tracker).
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
42
43
44 Documentation
45 -------------
46
47 README
48 ^^^^^^
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bullet...
frlan authored
49
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
50 Each plugin folder should contain at least a `README` file for
51 documentation.
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
52
53
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
54 Markup language
55 ###############
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
56
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bullet...
frlan authored
57 The `README` is intended to be written in `Restructured Text
58 <http://sphinx.pocoo.org/rest.html>`_ (as this document is) and
59 therefore should work with ``rst2html`` or similar tools. The reason
60 for this is that this information is used to generate the content of
61 the `Plugins Website <http://plugins.geany.org>`.
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
62
63
64 Recommended contents
65 ####################
66
67 The documentation should include a detailed description on features
68 offered by the plugins and usage of those features. It should also
69 include some basic information to make it easier for users to get in
70 touch with the developer(s) or to find further help in case of any
71 issues. You can use some of the other `README` files to get a
72 general idea of what should be in the file, but generally it should
73 contain:
74
75 * author(s) of plugin and their mail addresses
76 * external web site (if any)
77 * known issues
78 * bug tracker
79 * dependencies
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
80
81
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
82 Committing
83 ----------
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
84
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
85 General
86 ^^^^^^^
87
88 * Commit one thing at a time, do small commits. Commits should be
89 meaningful and not too big when possible; multiple small commits are
90 good if there is no good reason to group them.
91 * Use meaningful name and email in the Author and Committer fields.
92 This helps knowing who did what and allows to contact the author if
93 there is a good reason to do so (unlikely, but can happen). Using
94 the email address associated with your GitHub account will allows
95 for better integration with the website's hyperlinking to accounts
96 features.
97 * When working on a new feature, create a new branch for it. When
98 merging it, use the --no-ff option to make sure a merge commit will
99 be created to better track what happened. However, if the feature
100 only took one commit you might merge it fast-forward since there is
101 not history to keep together.
102
103
104 Commit messages
105 ^^^^^^^^^^^^^^^
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
106
5afe76c @codebrainz Add more information to the HACKING file
codebrainz authored
107 Follow the standard Git formatting:
108
109 * No line should use more than about 80 characters (around 72 is best).
110 * The first line is the commit's summary and is followed by an empty
111 line. This summary should be one line and one line only, thus less
112 than 80 characters. This summary should not include any punctuation
113 unless really needed. See it as the subject of an email: keep it
114 concise and as precise as you can, but not tool long.
115 * If you're working on a specific plugin, prefix the summary line
116 with the lower case name of the plugin (same as the directory name)
117 to make it easier to know which commit affected which plugin without
118 having to thoroughly examine the commit diff itself. No prefix is
119 needed if the commit is non-plugin specific or affects only files
120 outside of the plugins' directories.
121 * Following lines are optional detailed commit information, with
122 paragraphs separated by blank lines. This part should be as long as
123 needed to describe the commit in depth, should use proper
124 punctuation and should include any useful information, like the
125 motivation for the patch and/or any valuable details the diff itself
126 doesn't provide or make clear. Make it as complete as you think
127 it makes sense, but don't include an information that is better
128 explained by the commit's diff.
129
130 It is OK to use ASCII formatting like bullet list using "*" or "-",
131 etc. if useful, but emphasis (bold, italic, underline) should be
132 avoided.
133
134 Example::
135
136 Ask the user if spawn fails in utils_open_browser()
137
138 Ask the user to configure a valid browser command if spawning it
139 fails rather than falling back to some arbitrary hardcoded defaults.
140
141 This avoid spawning an unexpected browser when the configured one is
142 wrong, and gives the user a chance to correctly fix the preference.
dd8eb8d @frlan Addming some minor requirements for documentation to HACKING file
frlan authored
143
b12c8aa @frlan Adding a short note about l10n/I18n into HACKING
frlan authored
144 Coding and Plugin structure
145 ===========================
146
147 I18n/l10n
148 ---------
149
150 Geany-Plugins is supporting localisation of your plugin. To make
151 usage of it, there needs to be done:
152
4335e4d @frlan Some further smaller changes on HACKING and fix indention of l10n-bullet...
frlan authored
153 * Mark each string which should be translatable with the gettext macro
154 ``_()`` or ``N_()`` for static strings. As an example the string
155 ``"Hello World"`` might become ``_("Hello World")``.
156 * Add files with translateable strings into ``po/POTFILES.in``. You
157 should group them for your plugin as done for the other. Each files
158 needs to be put into one line with complete relative path from
159 plugin root directory. E.g. ``myplugin/src/myplugin.c``
Something went wrong with that request. Please try again.