|
|
||
|
Support Ex-Jakarta |
The Project's codebase is maintained in shared information repositories using either Subversion (svn.apache.org) or CVS (cvs.apache.org). Only Committers have write access to these repositories. Everyone has anonymous read access. More information on the Jakarta source code repositories is available here. All Java Language source code in the repository must be written in conformance to the "Code Conventions for the Java Programming Language" as published by Sun, or in conformance with another well-defined convention specified by the subproject. LicenseAll source code committed to the Project's repositories must be covered by the Apache License or contain a copyright and license that allows redistribution under the same conditions as the Apache License. Committers should update the copyright notice on the Apache License to include the current year when they revise a source file. If it is 2005, and you revise a source file from 1999, change the copyright notice in the license to cite "1999, 2005". If the file was from 2004, we would change it to 2004-2005. And so forth. This will happen most often in the early part of a year, but maintenance of the copyright date should occur year-round, as needed. Any code, document, or binary that is committed to the Project's repositories, but not being donated to the ASF, must be clearly marked as such. All contributors should have a Contributor License Agreement on file. Status FilesEach of the Project's active source code repositories contain a file named STATUS which is used to keep track of the agenda and plans for work within that repository. The status file includes information about release plans, a summary of code changes committed since the last release, a list of proposed changes that are under discussion, brief notes about items that individual developers are working on or want discussion about, and anything else that may be useful to help the group track progress. It is recommended that the active status files are automatically posted to the developer mailing lists three times per week. BranchesGroups are allowed to create a branch for release cycles, etc. They are expected to merge completely back with the main branch as soon as their release cycle is complete. All branches currently in use should be documented by the respective projects. ChangesSimple patches to fix bugs can be committed then reviewed. With a commit-then-review process, the Committer is trusted to have a high degree of confidence in the change. Doubtful changes, new features, and large scale overhauls need to be discussed before committing them into the repository. Any change that affects the semantics of an existing API function, the size of the program, configuration data formats, or other major areas must receive consensus approval before being committed. Related changes should be committed as a group, or very closely together. Half-complete projects should never be committed to the main branch of a development repository. All code changes must be successfully compiled on the developer's platform before being committed. Also, any unit tests should also pass. The current source code tree for a subproject should be capable of complete compilation at all times. However, it is sometimes impossible for a developer on one platform to avoid breaking some other platform when a change is committed. If it is anticipated that a given change will break the build on some other platform, the committer must indicate that in the commit message. A committed change must be reversed if it is vetoed by one of the voting members and the veto conditions cannot be immediately satisfied by the equivalent of a "bug fix" commit. The veto must be rescinded before the change can be included in any public release. PatchesPatches are a way to apply updates (to code, documentation). They take the form of a specially formatted difference listing that can be automatically applied to the source that is to be changed. When a specific change to a product is proposed for discussion or voting on the appropriate development mailing list, or contributed as part of a bug report, it should be presented in the form of a file suitable as input to the patch command. To avoid disappointment, please contact the developer mailing list before starting on any major patch, particularly one that provides new functionality. Perhaps someone else is already working in a related area, or the proposed patch may not fall within the remit of project, or there may be a better way to solve the problem. Creating PatchesThe patch should be created by using the diff -u command from the original software file(s) to the modified software file(s). It is recommended that you create patches against the latest version of the software in the source code repository in order to avoid conflicts. This will also ensure that you are not submitting a patch for a problem that has already been resolved. Some projects may use different branches for different releases - check with the developer mailing list to determine the correct repository details. For projects using Subversion
svn diff Main.java >> patchfile.txt
or if you have to:
diff -u Main.java.orig Main.java >> patchfile.txt
Some IDEs also have tools to simplify the creation of patches. Download the current source, make and test the changes, and use the IDE to create the patch. For Subversion access on Win32, there is a native command-line tool available, or there are a number of graphical tools including TortoiseSVN. You can also access Subversion from IDEs such as Eclipse and Netbeans with the appropriate plugins. More detailed instructions for accessing Jakarta's source code repositories with various tools and IDEs, including anonymous access, can be found here. All patches necessary to address an action item should be concatencated within a single patch file. If later modification to the patch proves necessary, the entire new patch should be posted and not just the difference between the two patches. Completely new files should not be provided as patches, as these are harder to read. These should be provided as separate files. Submitting PatchesExcept for very small changes, e.g. a typo in a document, patches should not be sent to mailing lists. Attachments can be stripped; inline patches can suffer line-wraps, and it takes extra bandwidth to send the details to everyone on the list. Not everyone needs or wants to get the patch itself. However, if it is appropriate to send the patch to the mailing list, the message should contain a Subject beginning with [PATCH] and a distinctive one-line summary in the subject corresponding to the action item for that patch. The preferred method of providing patches is via the relevant issue tracking system for the product, i.e. Bugzilla or JIRA. These make it much easier to track progress of a patch, and avoid the problems of lost or mangled attachments and wasted bandwith. There may already be a report which relates to the patch, in which case the files should be attached to that. Otherwise, please create a new issue with full details of the purpose of the patch. [Note: you cannot attach a file when creating a new Bugzilla issue; files can only be attached once the issue has been created.] An alternative is to place the patch file up on a website and send a message to the development list with the URL. This is not recommended unless other methods are impossible. Applying PatchesWhen committing a patch into the repository, please include the patch reference in the commit message. If the change is non-obvious, it may also be appropriate to include the patch reference in the code. However too many bug references may make the comments difficult to read. When a patch has been checked into the source code repository, the person who checked in the patch should update the issue tracker to note that the patch has been applied. If the patch has not been applied to the main branch, please note which branch was used. The issue tracker will send a message to the project mailing list, and will also send messages to other interested parties associated with the issue. It may also be appropriate to send a message to the person who sent the patch in as well as the mailing list specifying that the patch has been checked in. The reason is that not everyone watches commit messages and it is helpful for others to know what has been checked in and when in order to help prevent people from applying the patch at the same time. |
About Jakarta About Apache
Retired Subprojects |
|
|
||
