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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
.. _libmaple-contributing:
Contributing to libmaple
========================
First of all, thanks! Community contributions are what makes open
source great.
If your patch is minor (you've found a typo, you've added a new
function, etc.), feel free to just make a `forum post
<http://forums.leaflabs.com>`_ describing your changes.
If your changes are larger (you wrote a new library, you added support
for a new peripheral, etc.), we'd prefer you submit a pull request on
GitHub or send us a nicely-formatted patch via email.
.. contents:: Contents
:local:
.. _libmaple-faq-patches-preparing:
Preparing Your Patch
--------------------
Before submitting a patch, please make sure it complies with the
:ref:`coding standard <libmaple-coding-standard>`. Consistent style throughout
the source tree is an important implementation objective for us, and a
patch that doesn't comply with the coding standard we've set forth is
likely to be sent back until it follows the standard.
We would prefer if you release each new file you submit under the `MIT
license <http://www.opensource.org/licenses/mit-license.php>`_. See
e.g. `bkp.h
<https://github.com/leaflabs/libmaple/blob/master/libmaple/bkp.h#L1>`_
for an example, and the coding standard for more details. Code
released under the `Lesser GPL
<http://www.gnu.org/copyleft/lesser.html>`_ may be accepted for
Wirish, but will almost certainly be rejected for libmaple proper. We
will not accept patches released under the `GPL
<http://www.gnu.org/licenses/gpl.html>`_.
**We're not against the GPL**! It just doesn't suit our purposes for
libmaple. If you're interested in a GPLed library for ST
microcontrollers, check out `libopenstm32
<http://www.hermann-uwe.de/blog/libopenstm32-a-free-software-firmware-library-for-stm32-arm-cortex-m3-microcontrollers>`_.
Also note that :ref:`libraries <libraries>` released under the GPL are
fine, we just don't want any core libmaple or Wirish code to be GPLed.
.. _libmaple-faq-patches-github:
Submitting Via GitHub Pull Request (Preferred)
----------------------------------------------
The most convenient way for you to contribute patches is to submit a
pull request on `GitHub <https://github.com>`_. Github provides
excellent code review interfaces, which will make it easy for us at
LeafLabs to communicate with you (and each other) about your patch.
It also makes it easy for us to merge your patch into the libmaple
source tree when the time comes.
The steps to submit a pull request are as follows:
1. If you don't already have one, get a `GitHub account
<https://github.com/plans>`_ (free).
2. Fork libmaple, then clone your fork to the computer you code on.
GitHub provides detailed instructions on `forking and cloning a
repository <http://help.github.com/fork-a-repo/>`_.
3. Push your commits to your GitHub libmaple fork (see instructions
linked in Step 2 for a step-by-step walkthrough on how to do this).
Please add a signed-off-by line to your commits which certify your
`developer certificate of origin
<http://elinux.org/Developer_Certificate_Of_Origin>`_ [#fcert]_.
For example, if your name is "John Smith", and your email address
is "jsmith@example.com", just include the following line at the
bottom of your commit messages:
``Signed-off-by: John Smith <jsmith@example.com>``
If you've configured Git to know your name and email, you can
instruct it to insert this line automatically by calling ``git
commit`` with the ``-s`` flag.
4. `Submit a pull request <http://help.github.com/pull-requests/>`_ to
the LeafLabs version of libmaple.
.. _libmaple-faq-patches-email:
Submitting Via Email
--------------------
If you're unfamiliar with Git or would prefer not to use GitHub, you
can always send us a patch via email at info@leaflabs.com. We'd love
it if you used the `Linux kernel patch format
<http://linux.yyz.us/patch-format.html>`_, but please at least include
the following information in your email:
1. How you generated your patch (arguments to ``diff``, etc.)
2. What git branch/commit or libmaple version your patch applies to
3. A one-line summary of your changes, along with any other details
you think we should know.
4. A sign-off line certifying your `developer certificate of origin
<http://elinux.org/Developer_Certificate_Of_Origin>`_ [#fcert]_.
.. _libmaple-git-resources:
Git Resources
-------------
If you'd like to learn more about Git, we recommend the following
resources:
* `The Git Community Book <http://book.git-scm.com/index.html>`_: A
collaboratively edited book on Git.
* `Pro Git <http://progit.org/book/>`_: despite its title, this is a
fairly beginner-friendly source of information.
* `Git - Revision Control Perfected (Linux Journal)
<http://www.linuxjournal.com/content/git-revision-control-perfected>`_:
Despite a title that makes it sound like it was written by a
marketing department, this is a very good introductory article on
basic Git concepts, and a solid primer on Git's internals.
- `GitPhraseBook (openembedded.org)
<http://www.openembedded.org/index.php/GitPhraseBook>`_: A
cookbook-style list of common Git problems and their solutions.
* `Understanding Git Conceptually
<http://www.eecs.harvard.edu/~cduan/technical/git/>`_: a good,
introductory tutorial on Git's fundamental concepts.
* `Git for Computer Scientists
<http://eagain.net/articles/git-for-computer-scientists/>`_: if
you're comfortable with directed acyclic graphs, this resource
explains Git's functionality in graph-theoretic terms.
.. highlight:: text
.. rubric:: Footnotes
.. [#fcert] Including this line indicates that you certify the following::
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
This may seem arbitrary, but it helps ensure that libmaple
remains open source.
|
