No subject
Tue Aug 19 22:18:26 CEST 2008
code. Please read the following carefully when you are working with
U-Boot and want to send your modifications back to the public source
tree:
(1) Comply with the coding standards:
All contributions to U-Boot must conform to the Linux kernel
coding style; see the file "Documentation/CodingStyle" in your
Linux kernel source directory.
Please note that U-Boot is implemented in C (and to some small
parts in Assembler); no C++ is used, so please do not use C++
style comments (//) in your code.
Please also comply with the following formatting rules:
- remove any trailing white space
- use TAB characters for indentation, not spaces
- make sure NOT to use DOS '\r\n' line feeds
- do not use more than 2 consecutive empty lines in source files
- do not add trailing empty lines to source files
Submissions which do not conform to the standards will be rejected
with a request to reformat the changes.
(2) Make separate commits for logically separate changes.
Unless your patch is really trivial, you should not be sending
out a patch that was generated between your working tree and your
local commit head. Instead, always make a commit with complete
commit message and generate a series of patches from your
repository. It is a good discipline.
Describe the technical details of the change(s).
If your description starts to get long, that's a sign that you
probably need to split up your commit to finer grained pieces.
Make sure to update the CHANGELOG file appropriately.
Don't forget to register yourself in the MAINTAINERS file if you
add new processor or board support.
(3) Use branches for sets of modifications that belong together
logically.
If you're adding support for a new processor or a new board or a
bigger new feature (like re-writing all code that deals with NAND
flash) then we strongly recommend to keep all this work in a
separate branch. This may not be strictly necessary for your own
work, but it will make your own life easier in the long term, and
if you ever intend to allow direct pulling from your tree this
will be mandatory.
See http://source.denx.net/en/view/Documents/GitAdvancedUse#Linux_subsystem_maintenance_usin
for some excellent advice.
(4) Always send plain patches only.
Do not send complete source files or tarballs with sources or
tarballs with patches. Do not send compressed or encoded files.
Anything that cannot be applied directly as a patch may be
rejected.
(5) Generate your patch using git/cogito out of your commits.
git diff tools generate unidiff which is the preferred format.
You do not have to be afraid to use -M option to "git diff" or
"git format-patch", if your patch involves file renames. The
receiving end can handle them just fine.
Please make sure your patch does not include any extra files
which do not belong in a patch submission. Make sure to review
your patch after generating it, to ensure accuracy. Before
sending out, please make sure it cleanly applies to the "master"
branch head.
(6) Sending your patches.
People on the U-Boot mailing list needs to be able to read and
comment on the changes you are submitting. It is important for a
developer to be able to "quote" your changes, using standard
e-mail tools, so that they may comment on specific portions of
your code. For this reason, all patches should be submitting
e-mail "inline". WARNING: Be wary of your MUAs word-wrap
corrupting your patch. Do not cut-n-paste your patch.
Plain text(!) MIME attachments are acceptable, too.
Remember that there is a size limit of 40 kB for postings on the
mailing list. If you find yourself running into this limit this is
an indication that you probably need to split up your commit into
smaller pieces.
It is common convention to prefix your subject line with [PATCH].
This lets people easily distinguish patches from other e-mail
discussions.
"git format-patch" command follows the best current practice to
format the body of an e-mail message. At the beginning of the
patch should come your commit message, ending with the
Signed-off-by: lines, and a line that consists of three dashes,
followed by the diffstat information and the patch itself. If you
are forwarding a patch from somebody else, optionally, at the
beginning of the e-mail message just before the commit message
starts, you can put a "From: " line to name that person.
You often want to add additional explanation about the patch,
other than the commit message itself. Place such "cover letter"
material between the three dash lines and the diffstat.
Never send compressed or encoded messages. Do not let your e-mail
client send quoted-printable. Many popular e-mail applications
will not always transmit a MIME attachment as plain text, making
it impossible to comment on your code. A MIME attachment also
takes a bit more time to process. This does not decrease the
likelihood of your MIME-attached change being accepted, but it
makes it more likely that it will be postponed.
Exception: If your mailer is mangling patches then someone may
ask you to re-send them using MIME.
NEVER SEND HTML MESSAGES TO THE LIST. NEVER!!!
Note that your maintainer is subscribed to the U-Boot mailing
list so there is no need to put him on separate Cc:
(7) Sign your work
To improve tracking of who did what, we've borrowed the
"sign-off" procedure from the Linux kernel project on patches
that are being emailed around. Although U-Boot is a lot smaller
project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for
the patch, which certifies that you wrote it or otherwise have
the right to pass it on as a open-source patch (more precisely:
as Free Software under GPL). The rules are pretty simple: if you
can certify the below:
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.
then you just add a line saying
Signed-off-by: Random J Developer <random at developer.example.org>
Releases:
=========
Our intention is to produce "releases" of U-Boot much more frequently
now. We will use the following numbering scheme for U-Boot releases:
version.patchlevel.sublevel
Releases where "sublevel" is zero will be called "stable". The
previous release was 1.1.3, and we're working on 1.1.4 now, so the
next "stable" release might be called "1.2.0".
That's it for now. Hope you git along with all this Great New Stuff :-)
Best regards,
Wolfgang Denk
--
Software Engineering: Embedded and Realtime Systems, Embedded Linux
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
By the way, ALL software projects are done by iterative prototyping.
Some companies call their prototypes "releases", that's all.
More information about the U-Boot
mailing list