RTEMS CVS Repository Writing
The RTEMS Project provides read/write access to the CVS repository for all significant developers. Maintainers are also encouraged to used the Bugzilla Problem Reporting System.
Authenticated access is provided via the SSH protocol. Please provide us with your public key, which you can generate via the ssh-keygen program. This will store your public key in the file .ssh/identity.pub in your home directory. When establishing SSH access, you will have to provide this file and some other details to the person handling the system administration details.
Once we have this information we will set up an account on the machine www.rtems.org and inform you by mail. At this point you should be able to check out a tree with CVS and add yourself to the MAINTAINERS file to test write access. See the XXX Checking in a change for how to proceed with checking in your changes.
Setting up your local CVS tree
Once you can login to the machine, it's trivial to start using ssh from your remote machine. Set CVS_RSH in your environment to "ssh". Then issue the command
cvs -z 9 -d :ext:USERNAME@www.rtems.com:/usr1/CVS co rtems
where USERNAME is your user name at www.rtems.com. This will check out a new CVS tree that you should be able to work with in the normal fashion, including committing changes.
It is also possible to convert an existing CVS tree to use ssh by replacing all the "Root" files in the local tree with the following contents:
USERNAME@www.rtems.com:/usr1/CVSTo avoid the nuisance of having to supply your passphrase for each
operation, you may want to use ssh-agent(1) followed by ssh-add(1) and entering your passphrase once for all. Either start your session as a child of ssh-agent or run it as a daemon and set the values of the environment variables SSH_AUTHENTICATION_SOCKET and SSH_AGENT_PID in each relevant process to what ssh-agent prints when it starts. To avoid messages about (lack of) X11 forwarding, put in your $HOME/.ssh/config an entry like:
Host www.rtems.com ForwardX11 no
When you check in changes to our web pages, they will automatically be checked out into the web server's data area.
Write access policies
The RTEMS project grants some developers various levels of write access to the RTEMS master sources. CVS doesn't provide fine grained control over access to the repository; therefore, we depend on each developer to follow the appropriate policies.
- Global write permission - A very limited number of developers have global write permission over the entire repository. They may check in changes to any part of the RTEMS source without approval from anyone else. They may also approve other people's changes to any part of the operating system.
- Localized write permission - This is for people who have primary responsibility for ports, BSPs, libraries, or significant hunks of code in the operating system. These folks are allowed to make changes in code they maintain without approval from anyone else, and approve other people's changes in those files. They must get approval from the appropriate maintainers for changes elsewhere in the operating system.
Maintainers of a port maintain the files in cpukit/score/cpu/CPU/, the configure fragments for the port, documentation for the port, test cases for features or bugs specific to this port, and the BSPs for the port. Port maintainers do not have approval rights in other files.
- Write after approval - This is folks that make regular contributions, but do not fall into one of the two previous categories. People with write after approval need to submit their patches to the list; once the patches have been approved by the appropriate maintainers the patches may be checked into the RTEMS source
s. The steering committee can (XXX link) approve for write access any person known to submit good patches. The list of folks with write access to the repository can be found in the MAINTAINERS file in the RTEMS distribution.
Also note that fixes for obvious typos in ChangeLog files, docs, web pages, comments and similar stuff need not be approved. Just check in the fix. We don't want to get overly anal about checkin policies. When you have checked in a patch exactly as it has been approved, you do not need to tell that to people -- including the approver. People interested in when a particular patch is committed can check CVS or the http://www.rtems.com/ml/rtems-cvs/ list.
Everyone with CVS write access is free to update files maintained outside the tree from their official versions without explicit write approval.
Any maintainer with CVS write access may create and use a branch for development, including outside the parts of the compiler they maintain, provided that changes on the branch meet RTEMS Licensing Requirements. Merging such developments back to the mainline still needs approval in the usual way.
All changes must be tested according to the instructions for testing patches before they are checked in. If you wrote the patch yourself, you should test it yourself, unless there is a reason why someone else must do it for you (for instance, if you are fixing a problem on a system you do not have access to). If you are checking in a patch for someone else, you only need to test it if they did not.
You must test exactly the change you intend to check in; it is not good enough to have tested an earlier variant. (Unless the only changes from the earlier variant are formatting and comment changes; if there are ANY changes to the code itself you should rebuild and test again.) It is a good idea to re-test patches which were submitted a long time ago before applying them, even if nothing appears to have changed.
When you post your change to rtems-patches, state the canonical name(s) of the platform(s) you used for testing. This should include the RTEMS version, CPU family, CPU model, and target board.
These rules are designed to ensure that checked-in code does not contain bugs that prevent other people from continuing to get their work done. There will always be bugs, but these rules help to minimize the amount of time where the tree does not build at all. Repeated failure to adhere to these rules could result in the revocation of check-in privileges by the Steering Committee.
Checking in a change
The following is meant to provide a very quick overview of how to check in a change. It is not meant to be a replacement for the CVS manual but instead a supplement. The CVS manual is distributed as part of the CVS sources as a texinfo file. [] contains a link to an reasonably simple introduction to CVS.
In all the commands listed below, you can give an explicit list of filenames to the cvs command. We recommend you list files explicitly when performing checkins to avoid accidental checkins of local code. We prefer that each CVS checkin be of a complete, single logical change, which may affect multiple files. The log message for that checkin should be the complete ChangeLog entry for the change. This makes it easier to correlate changes across files, and minimizes the time the repository is inconsistent. If you have several unrelated changes, you should check them in with separate cvs commit commands.
- Sync your sources with the master repository via "cvs
update" before attempting a checkin; this will save you a little time if someone else has modified that file since the last time you synced your sources. It will also identify any files in your local tree that you have modified.
- Apply the patch to your local tree and update the ChangeLog file.
Use the current date for the ChangeLog entry, not the time that the patch was submitted.
- Make sure to rebuild any generated files that would be affected by
the patch. Make sure to check them in along with the files explicitly modified by the patch.
- We recommend using "cvs diff" after applying a patch to a
local tree. Review the output to make sure that only the changes you wanted to check in will be checked in. Also check to see if the copyright dates need to be updated.
- Use "cvs commit" to check in the patch. You can enter
the log message via the "-m" argument to commit, or wait for the editor window to appear and enter the log message in the editor window.
- After exiting the editor, CVS will connect to the RTEMS cvs server
and check in your changes. When your prompt returns the checkin should be finished. A message will be sent to the rtems-cvs mailing list indicating that a change was made. CVS will provide a message if an error occurs and it will not check in any files. [NOTE: The RTEMS CVS server has been known to fail with a message like "pipe broken". If this occurs, then only a subset of the files have been checked in. Please repeat the previous submit command until all files are committed].
Example check-in session
Here's an check-in session for an example patch by myself. This was the ChangeLog for this change:
2004-05-03 Joel Sherrill <firstname.lastname@example.org> PR 123/bsps * README: Fixed use of incorrect commands to bootloader.
For convenience, I write the ChangeLog entry into a temporary file that I habitually call changes-XXX. I find that this makes it easier to deal with the ChangeLog entry in the next steps. The RTEMS scripts module in CVS includes a script called mkChangeLogList which is helpful in preparing a ChangeLog entry.
NOTE from JoelSherrill: I has a few scripts which I use to help me write ChangeLog entries in the right format. Ask nicely and I might make you a tester. :)
First, I sync my local repository.
This ensures that any recently checked in changes are reflected in my local source tree before I proceed to commit new changes.
rtems# pwd /usr1/rtems/work/rtems/c/src/lib/libbsp/i386/pc386 rtems# cvs update -Pd ? changes-XXX ? README.save M README M bsp_specs
The question marks indicate files in my local repository that are not part of the official sources. The "M" indicates files I've changed locally for some unrelated work -- thus I have to be careful to avoid checking them in. A "U" would have indicated a file that CVS updated because my local copy was out of date relative to the master sources.
The local repository is now up to date.
Add ChangeLog entry by hand
ChangeLog entries should be handled as straight text; patches against ChangeLogs rarely apply correctly.
Review changes for correctness
The patch and its associated ChangeLog entry are in my local tree; now I run cvs diff on the modified files and review the output, verifying that it only contains the changes we want.
rtems# cvs diff -c3p README
Review the changed files to see if any copyrights need updating, in this particular case README needed their copyrights updated.
rtems# vi README
Commit the changes to the central repository
rtems# cvs commit -F changes-XXX ChangeLog README
The -F changes-XXX argument specifies that the contents of the file changes-XXX are to be used as the comment. If you do not specify this argument, then the editor will be started and you will have to enter the log message. The lines starting with CVS: are automatically added by CVS and will be automatically removed. The following is an example of how this will look if the editor is invoked:
2004-05-03 Joel Sherrill <email@example.com> PR 123/bsps * README: Fixed use of incorrect commands to bootloader. CVS: ---------------------------------------------------------------------- CVS: Enter Log. Lines beginning with `CVS:' are removed automatically CVS: CVS: Committing in . CVS: CVS: Modified Files: CVS: ChangeLog README CVS: ----------------------------------------------------------------------
Now write & quit from the editor, and CVS will start the actual checkin process....
Checking in ChangeLog; /usr1/CVS/rtems/c/src/lib/libbsp/i386/pc386/ChangeLog,v <-- ChangeLog new revision: 1.746; previous revision: 1.745 done Checking in README; /usr1/CVS/rtems/c/src/lib/libbsp/i386/pc386/bitmap.c,v <-- bitmap.c new revision: 1.6; previous revision: 1.5 done rtems #
And that's it!
When creating a branch for development, you should first tag the branchpoint.