CONTRIBUTING.md

XRootD Development Model and How to Contribute

Versioning

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:

• The first number designates a major version. Major versions may introduce binary incompatibility with previous major versions and may require code dependent on libraries in the new major version to be recompiled. Generally, such requirements are limited to code that enhances XRootD functionality (e.g. plug-ins). User application code that only uses public APIs should continue to work unchanged. Consequently, major versions are infrequent and are introduced approximately every 5 years.

• The second number increments within the major version and designates a minor version. Minor versions introduce new features within a major version. They are binary compatible with all versions within the major version and occur as often as needed to address community needs. On average, there are a few minor versions per year.

• The last digit increments whenever changes are applied to a minor version to fix problems. These occur at random frequency, as often as necessary to fix problems. Since patch versions represent the minimum change necessary to fix a problem they provide the forward path for problem resolution.

• When the first number increments, the second and third numbers are reset to zero and when the second number increments the third number is reset to zero.

• A fourth number may be added by EOS as indication that the version of XRootD used by EOS has been patched after the official release. Patches introduced in an intermediate release for EOS will be likely included into the following patch release, unless it is a temporary fix affecting only EOS.

Library versions

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.

Releases and Release Procedure

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.

Stable and Develoment Branches

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.

Guidelines for Contributors

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.

Deciding what to base your work on

In general, always base your work on the oldest branch that your change is relevant to.

• A bug fix should be based on the latest release tag in general. If the bug is not present there, then base it on 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.

• A new feature should be based on 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.

• Corrections and enhancements to a topic not yet merged into 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.

Make separate commits for logically separate changes

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.

Describe your changes well

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

• explains the problem the change tries to solve, i.e. what is wrong with the current code without the change.

• justifies the way the change solves the problem, i.e. why the result with the change is better.

• alternate solutions considered but discarded, if any.

You should use the imperative to describe your changes, for example:

Change default value of foo to 1024

instead of

This commit changes the default value of foo to 1024

or

Changed default default value of foo to 1024

Examples of good commit messages:

Author: Andrew Hanushevsky <abh@slac.stanford.edu>
Date:   Thu Jun 8 18:06:01 2023 -0700

    [Server] Allow generic prepare plug-in to handle large responses, fixes #2023

Author: Brian Bockelman <bbockelman@morgridge.org>
Date:   Sat Feb 18 13:15:49 2023 -0600

    Map authentication failure to HTTP 401

    The authentication failure error message was previously mapped to
    HTTP 500 (internal server error).  401 Unauthorized (despite its name)
    is what HTTP servers typically utilize for authentication problems.

References to other commits, issues, pull requests, etc

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

git show -s --pretty=reference <commit>

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.