[docs] Add docs/CONTRIBUTING.md

Closes: xrootd#1991.
Co-authored-by: Andrew Hanushevsky <[email protected]>

docs/CONTRIBUTING.md

@@ -0,0 +1,234 @@
+## 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](https://www.usenix.org/legacy/publications/library/proceedings/als00/2000papers/papers/full_papers/browndavid/browndavid_html/)
+and
+[here](https://www.akkadia.org/drepper/dsohowto.pdf).
+
+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](https://xrootd.slac.stanford.edu/dload.html) 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 at https://github.com/git/git/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 <[email protected]>
+Date:   Thu Jun 8 18:06:01 2023 -0700
+
+    [Server] Allow generic prepare plug-in to handle large responses, fixes #2023
+```
+
+```
+Author: Brian Bockelman <[email protected]>
+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.