![]() |
XRootD
|
XRootD software releases are organized into major, minor and patch versions, with the intent that installing minor version releases with the same major version do not take long to perform, cause significant downtime, or break dependent software. New major versions can be more disruptive, and may substantially change or remove software components. Releases are assigned version numbers, such as "5.6.0", where:
When a library evolves compatibly: existing interfaces are preserved, but new ones are added the library’s minor version number must be incremented. Since nothing has been done that would break applications constructed earlier, it is OK for older applications to be linked with the newer library at run-time.
If the interfaces in a library shared object change incompatibly, then the major revision number associated with the library must be incremented. Doing so will cause run-time linking errors for the applictions constructed with the older versions of the library and thus will prevent them from running, as opposed to crashing in an uncontrollable way.
More information on library versioning is available here and here.
The project policy is that a change to public interfaces (as defined in the installed headers) requires a major release - bumping the major version number.
Feature releases with current developments will normally be built a few times per year. Each master
release is preceded by one or more release candidates that get tested for bugs and deployment issues in a possibly wide range of environments. When the release candidates are deemed sufficiently stable, then the final release is built.
In addition to the master
or "feature" releases, "bug fix" releases may be built whenever needed. These are for bug fixes only, so they normally should not need release candidates (due to the reduced need for additional testing).
RPM packages are built for each release, including release candidates. All the packages are pushed to the testing yum repository. Additionally, all the bug fix releases and all the final master
releases are pushed to the stable repository. See the download page for details.
Beginning with XRootD 5.6.0, the development model is based on two long-term branches: master
, and devel
.
The master
branch is the stable branch. It contains released versions of XRootD and may also contain unreleased bug fixes which do not require a new minor release. Each patch release for a given major+minor series is created from the master
branch by adding any required bug fixes from the devel
branch to the master
branch and tagging a new release, such that all XRootD releases may be found linearly in git history.
The devel
branch is the development branch where all new features and other developments happen. Each new feature release is created by rebasing, then (perharps partially) merging the devel
branch into the master
branch, then tagging the relase on master
. The devel
branch will be kept current with the master
branch by rebasing it after each patch release, to ensure that all bug fixes are always included in both master
and devel
.
This section provides guidelines for people who want to contribute code to the XRootD project. It is adapted from git's own guidelines for contributors, which can be found in their repository on GitHub at https://github.com/git/git/blob/master/Documentation/SubmittingPatches.
In general, always base your work on the oldest branch that your change is relevant to.
master
. Otherwise, if it is only present on devel
, or a feature branch, then base it on the tip of devel
or the relevant feature branch.devel
in general. If the new feature depends on topics which are not yet merged, fork a branch from the tip of devel
, merge these topics to the branch, and work on that branch. You can get an idea of how the branches relate to each other with git log --first-parent master..
or with git log --all --decorate --graph --oneline
.devel
should be based on the tip of that topic. Before merging, we recommend cleaning up the history by squashing commits that are fixups for earlier commits in the same branch rather than committing a bad change and the fix for it in separate commits. This is important to preserve the ability to use git bisect to find which commit introduced a bug.In your commits, you should give an explanation for the change(s) that is detailed enough so that a code reviewer can judge if it is a good thing to do or not without reading the actual patch text to determine how well the code actually does it.
If your description is too long, that's probably a sign that the commit should be split into finer grained pieces. That being said, patches which plainly describe the things that help reviewers checking the patch and future maintainers understand the code are very welcome.
If you are fixing a bug, it would be immensely useful to include a test demonstrating the problem being fixed, so that not only the problem is avoided in the future, but also reviewers can more easily verify that the proposed fix works as expected. Similarly, new features which come with accompanying tests are much more likely to be reviewed and merged in a timely fashion.
When developing XRootD on your own fork, please make sure that the existing test suite is not broken by any of your changes by pushing to a branch in your own fork and checking the result of the GitHub Actions runs.
The log message that explains your changes is just as important as the changes themselves. The commit messages are the base for creating the release notes for each release. Hence, each commit message should clearly state whether it is a bug fix or a new feature whenever that is not immediately obvious from the nature of the change itself. Moreover, it is very important to explain not only what your code does, but also why it does it.
The first line of the commit message should be a short description of up to about 50 characters (soft limit, hard limit at 80 characters), and should skip the full stop. It is encouraged, although not necessary, to include a tag which identifies the general area of code being modified, for example "[Server]", "[XrdHttp]", etc. If in doubt, please check the git log for similar files to see what are the current conventions.
After the title sentence, you should include a blank line and then the body of the commit message, which should be a meaningful description that
You should use the imperative to describe your changes, for example:
instead of
or
Examples of good commit messages:
Sometimes, it may be useful to refer to the pull request on GitHub, an open issue which a commit fixes/closes, or simply an older commit which may have introduced a regression fixed by the current change. When referring to older commits, try to use the same format as produced by
For issues, add a "Closes: #nnnn" or "Fixes: #nnnn" tag to the body of the commit message (or, even better, to the pull request description). When linking a change to a specific issue or pull request, please verify in the GitHub website that the association actually worked. Depending on how you phrase your message, this may not happen automatically. In that case, it is also possible to use the "Development" side panel on the right to manually create the connection between pull requests and issues. If you intend to have your changes be part of a particular release which is not the next release being planned, you may also mark your pull request for inclusion in the desired release by using the "Milestone" side panel on the right. This can be used as an alternative method of marking a change as "bug fix" or "feature", depending on if it will only be included in the next patch release or feature release. Any changes which require a major release must be marked with the appropriate milestone.