mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
05676d1abe
* Consolidate documentation under doc/ directory
Move user-facing guides from release_docs/ and doxygen/ into a single
doc/ root. release_docs/ now holds only release artifacts (changelogs,
history, release process, maintainer info).
- git mv release_docs/INSTALL*.md, USING_*.md, README_HPC.md,
BuildSystemNotes.md, AutotoolsToCMakeOptions.md,
HDF5_Library_2.0.0_Migration_Guide.md → doc/
- git mv doxygen/ → doc/doxygen/
- Update CMakeLists.txt: HDF5_DOXYGEN_DIR and add_subdirectory path
- Update CMakeInstallation.cmake: all install paths for moved files
- Update bin/make_vers: hardcoded doxygen/ path substitution
- Update doc/doxygen/CMakeLists.txt: EXAMPLES_DIRECTORY and comments
- Update README.md, CONTRIBUTING.md, SECURITY.md, config/README.md,
release_docs/RELEASE_PROCESS.md: links to moved files
- Update doxygen .dox files: release_docs/ URLs for moved guides
- Rewrite release_docs/README.md for narrowed scope
* Add HDF5_DOCS_DIR variable for doc/ root path
Introduce HDF5_DOCS_DIR = \${HDF5_SOURCE_DIR}/doc so that
CMakeInstallation.cmake and future callers reference the doc/
directory symbolically rather than by hardcoded path.
HDF5_DOXYGEN_DIR is now derived from HDF5_DOCS_DIR.
104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# The `release_docs` directory
|
|
|
|
This directory contains **release artifacts only**: changelogs, version history,
|
|
release process documentation, and maintainer information.
|
|
|
|
User-facing guides (installation, build instructions, platform-specific docs)
|
|
have been moved to the [`docs/`](../docs/) directory.
|
|
|
|
## Contents
|
|
|
|
### CHANGELOG.md (formerly RELEASE.txt)
|
|
|
|
This is the changelog for the current version of the library.
|
|
|
|
For a MAJOR release (or in `develop`) this file lists all the changes since the
|
|
last major version. For a MINOR release (or in a maintenance branch), this file
|
|
lists all the changes since the last release in the maintenance branch.
|
|
|
|
Examples:
|
|
|
|
* The file for HDF5 1.14.0 includes all the changes since HDF5 1.12.0
|
|
* The file for HDF5 1.10.9 includes all the changes since HDF5 1.10.8
|
|
* The file in `develop` includes all the changes since the last major release
|
|
* The file in `hdf5_1_14` includes all the changes since the last minor HDF5 1.14 release
|
|
|
|
### HISTORY files
|
|
|
|
The `HISTORY` files contain the history of this branch of HDF5. They fall into
|
|
three categories.
|
|
|
|
#### HISTORY-\[VERSION 1\]-\[VERSION 2\].txt
|
|
|
|
These files are created when we release a new major version and include all
|
|
the changes that were made to the `develop` branch while creating a major release.
|
|
|
|
#### HISTORY-\[VERSION\].txt
|
|
|
|
This file contains the changes that were made to a maintenance branch since
|
|
it split off from `develop`. It will also be found in the `develop` branch
|
|
when experimental releases have been created.
|
|
|
|
Note that we make no effort to bring maintenance branch `HISTORY` files back to
|
|
develop. If you want to compare, say, 1.10.4 with 1.12.3, you'd have to get
|
|
the history files from those releases and compare them by hand.
|
|
|
|
### RELEASE_PROCESS.md
|
|
|
|
Documentation for how releases are created and managed.
|
|
|
|
### MAINTAINERS.md
|
|
|
|
Maintainer information for the project.
|
|
|
|
## Creating new releases
|
|
|
|
### MAJOR release
|
|
|
|
* If there were experimental releases, merge the experimental `HISTORY` file
|
|
and the current `CHANGELOG.md` by category to create a separate, unified
|
|
file that ignores the experimental releases. Don't check this in yet or
|
|
clobber any existing `HISTORY`/`RELEASE` files, but put it someplace handy for
|
|
use in later steps.
|
|
|
|
* Create the new maintenance branch
|
|
|
|
In develop:
|
|
* Create the new `HISTORY-\[VERSION 1\]-\[VERSION 2\].txt` file
|
|
* If there is an experimental `HISTORY` file, add `CHANGELOG.md` to the beginning of it and use that
|
|
* Otherwise, start with `CHANGELOG.md`
|
|
* Add the introduction boilerplate like in the other `HISTORY` files (TOC, etc.)
|
|
* Delete any experimental `HISTORY` file
|
|
* Clear out `CHANGELOG.md`
|
|
|
|
Note that we're KEEPING any experimental release history information in the
|
|
`HISTORY-\[VERSION 1\]-\[VERSION 2\].txt` file, so do NOT use the merged file in
|
|
the above steps!
|
|
|
|
In the new maintenance branch:
|
|
* Create the new `HISTORY-\[VERSION\].txt` file
|
|
* If there is an experimental `HISTORY` file use the combined file you created earlier
|
|
* Otherwise, start with `CHANGELOG.md`
|
|
* Add the introduction boilerplate like in the other `HISTORY` files (TOC, etc.)
|
|
* Delete any experimental `HISTORY` file
|
|
* Clear out `CHANGELOG.md`
|
|
|
|
* Create the new release branch
|
|
|
|
In the new release branch:
|
|
* If there were experimental releases, use the combined file you created earlier as `CHANGELOG.md`
|
|
* Otherwise the `CHANGELOG.md` will be used as-is
|
|
|
|
### MINOR release
|
|
|
|
* Create the release branch
|
|
|
|
In the maintenance branch:
|
|
* Add the contents of `CHANGELOG.md` to the beginnnig of `HISTORY-\[VERSION\].txt`
|
|
* Clear out `CHANGELOG.md`
|
|
|
|
### EXPERIMENTAL release
|
|
|
|
* Add the contents of `CHANGELOG.md` to the beginnnig of `HISTORY-\[VERSION\].txt`
|
|
* Clear out `CHANGELOG.md`
|