Hello everybody.
the number of contributions to the U-Boot project has been continuously growing, and for some time I've been looking for more efficient ways to deal with all the patches and submissions. The current development cycle with a central CVS repository at SourceForge has a couple of problems:
* SF is slow, and it takes sometimes pretty long until check-ins are visible to the public. If the CVS server at SF is down, the whole U-Boot development stalls.
* CVS is cumbersome to use when it comes to handling branches. So far we avoided branches in U-Boot completely, with the result that several interesting contributions were blocked for a long time to avoid de-stabilization of the only branch we had - often so long until the patches were not applicable any more. Many other patches and contributions got delayed because of this for a long time, too.
* Every new commit to the only branch needed at least a certain amount of testing, so preparing the tree for a "release" was always pretty challenging. This resulted in long delays between releases, which in turn caused many people to use old code as base for new work which called for trouble later.
U-Boot Version 1.1.3, which was released on August 14, 2005, was the last release following this old development cycle.
Big changes are coming.
U-Boot Source Repository: =========================
Starting immediately, we use git (see http://git.or.cz/) as software configuration management (SCM) tool for U-Boot development.
Please see http://source.denx.net/en/Documents/GitDocs for some introductory information for git.
The "master repository" for U-Boot is available from
rsync://source.denx.net/git/u-boot.git or http://source.denx.net/git/u-boot.git
The CVS repository at SourceForge will be kept in sync with the git tree, but there is no guarantee how long I will do this, so it's use is deprecated. Use git, or feel free to use one of the 'porcelains' like cogito on top of git.
[FYI: SourceForge considers it "not an immediate priority" to host and support git based repositories.]
Submitting Patches: ===================
From now on I will also try to enforce stricter rules on contributed
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_main... 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@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