diff --git a/CMakeLists.txt b/CMakeLists.txt index 99c505f21c..b293913467 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -176,6 +176,7 @@ include(${PROJECT_SOURCE_DIR}/cmake/thirdparty/SetupSmithThirdParty.cmake) set(CMAKE_C_FLAGS ${SMITH_CMAKE_C_FLAGS}) set(CMAKE_CXX_FLAGS ${SMITH_CMAKE_CXX_FLAGS}) +include(${PROJECT_SOURCE_DIR}/cmake/SmithVersion.cmake) include(${PROJECT_SOURCE_DIR}/cmake/SmithConfigHeader.cmake) #------------------------------------------------------------------------------ diff --git a/cmake/SmithConfigHeader.cmake b/cmake/SmithConfigHeader.cmake index 39bb650dce..d141b51c47 100644 --- a/cmake/SmithConfigHeader.cmake +++ b/cmake/SmithConfigHeader.cmake @@ -4,35 +4,6 @@ # # SPDX-License-Identifier: (BSD-3-Clause) -#------------------------------------------------------------------------------ -# Version information that go into the generated config header -#------------------------------------------------------------------------------ -set(SMITH_VERSION_MAJOR 0) -set(SMITH_VERSION_MINOR 1) -set(SMITH_VERSION_PATCH 0) -string(CONCAT SMITH_VERSION_FULL - "v${SMITH_VERSION_MAJOR}" - ".${SMITH_VERSION_MINOR}" - ".${SMITH_VERSION_PATCH}" ) - -if (Git_FOUND) - ## check to see if we are building from a Git repo or an exported tarball - blt_is_git_repo( OUTPUT_STATE is_git_repo ) - - if(${is_git_repo}) - blt_git_hashcode(HASHCODE sha1 RETURN_CODE rc) - if(NOT ${rc} EQUAL 0) - message(FATAL_ERROR "blt_git_hashcode failed!") - endif() - - set(SMITH_GIT_SHA ${sha1}) - endif() - -endif() - -message(STATUS "Configuring Smith version ${SMITH_VERSION_FULL}") - - #------------------------------------------------------------------------------ # Create variable for every TPL #------------------------------------------------------------------------------ diff --git a/cmake/SmithVersion.cmake b/cmake/SmithVersion.cmake new file mode 100644 index 0000000000..82a85a671d --- /dev/null +++ b/cmake/SmithVersion.cmake @@ -0,0 +1,33 @@ +# Copyright (c) Lawrence Livermore National Security, LLC and +# other Smith Project Developers. See the top-level LICENSE file for +# details. +# +# SPDX-License-Identifier: (BSD-3-Clause) + +#------------------------------------------------------------------------------ +# Version information that go into the generated config header +#------------------------------------------------------------------------------ +set(SMITH_VERSION_MAJOR 0) +set(SMITH_VERSION_MINOR 1) +set(SMITH_VERSION_PATCH 0) +string(CONCAT SMITH_VERSION_FULL + "v${SMITH_VERSION_MAJOR}" + ".${SMITH_VERSION_MINOR}" + ".${SMITH_VERSION_PATCH}" ) + +if (Git_FOUND) + ## check to see if we are building from a Git repo or an exported tarball + blt_is_git_repo( OUTPUT_STATE is_git_repo ) + + if(${is_git_repo}) + blt_git_hashcode(HASHCODE sha1 RETURN_CODE rc) + if(NOT ${rc} EQUAL 0) + message(FATAL_ERROR "blt_git_hashcode failed!") + endif() + + set(SMITH_GIT_SHA ${sha1}) + endif() + +endif() + +message(STATUS "Configuring Smith version ${SMITH_VERSION_FULL}") diff --git a/src/docs/sphinx/dev_guide/gitflow-workflow.svg b/src/docs/sphinx/dev_guide/gitflow-workflow.svg new file mode 100644 index 0000000000..39dff59b85 --- /dev/null +++ b/src/docs/sphinx/dev_guide/gitflow-workflow.svg @@ -0,0 +1,183 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/docs/sphinx/dev_guide/gitflow_branching.rst b/src/docs/sphinx/dev_guide/gitflow_branching.rst new file mode 100644 index 0000000000..d8deb0b156 --- /dev/null +++ b/src/docs/sphinx/dev_guide/gitflow_branching.rst @@ -0,0 +1,115 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _gitflow-label: + +************************* +Gitflow Branching Model +************************* + +The Smith team uses the 'Gitflow' branch development model, which is +summarized in this section. See the `Atlassian Gitflow Description `_ +for more details. + +Gitflow is a branching model centered around software releases. It is a simple +workflow that makes clear which branches correspond to which phases of +development and those phases are represented explicitly in the structure of +the repository. As in other branching models, developers develop code locally +and push their work to a central repository. + +============================== +Main and Develop Branches +============================== + +The **main** and **develop** branches are the two main branches used in Gitflow. +They always exist and the distinction between them is central to the Gitflow +model. Other branches are temporary and used to perform specific development +tasks. + +The main branch records the official release history of the project. +Each time the main branch is changed, it is tagged with a new version number. +For a description of our versioning scheme, see :ref:`semver-label`. + +The develop branch is used to integrate and test new features and most +bug fixes before they are merged into main. + +.. important:: **Development never occurs directly on the main or develop + branches.** + +============================== +Topic Branches +============================== + +Topic branches are created off of other branches (usually develop) +and are used to develop new features and resolve issues before they +propagate to main. Topic branches are temporary, living only as long as they +are needed to complete a development task. + +Each new feature, or other well-defined portion of work, is developed on its +own topic branch, with changes being pushed to the central repository regularly +for backup. We typically include a label, such as "feature" or "bugfix", in +the topic branch name to make it clear what type of work is being done on the +branch. + +When a feature is complete, a pull request is submitted for review by other +team members. When all issues arising in a review have been addressed and +reviewers have approved the pull request, the feature branch is merged into +develop. + +.. important:: **Feature branches never interact directly with the main + branch.** + +============================== +Release Branches +============================== + +Release branches are another important temporary branch type in Gitflow: +When the team has decided that enough features, bug fixes, etc. have been +merged into develop (for example, all items identified for a release have +been completed), a release branch is created off of develop to finalize the +release. Creating a release branch starts the next release cycle on develop. +At that point, new work can start on feature branches for the next release. +Only changes required to complete the release are added to a release branch. +When a release branch is ready, it is merged into main and main is tagged +with a new version number. Finally, main is merged back into develop since +it may have changed since the release was initiated. + +The basic mechanics for generating a new release of the main branch for the +Smith project are described in :ref:`release-label`. + +.. important:: **No new features are added to a release branch. Only bug fixes, + documentation, and other release-oriented changes go into a + release branch.** + +============================== +Hotfix Branches +============================== + +The last important temporary branch type in Gitflow is a hotfix branch. +Sometimes, there is a need to resolve an issue in a released version on the +main branch. When the fix is complete, it is reviewed using a pull request +and then merged into both main and develop when approved. At this point, +main is tagged with a new version number. A dedicated line of development +for a bug fix, using a hotfix branch, allows the team to quickly address +issues without disrupting other parts of the workflow. + +.. important:: Hotfix branches are the only branches created off of main. + +============================== +Gitflow Illustrated +============================== + +The figure below shows how branches interact in Gitflow. + +.. figure:: gitflow-workflow.svg + + This figure shows typical interactions between branches in the Gitflow + workflow. Here, main was merged into develop after tagging version v0.1. + A fix was needed and so a hotfix branch was created. When the fix was + completed, it was merged into main and develop. Main was tagged + with version v0.2. Also, work was performed on two feature branches. + When one feature branch was done, it was merged into develop. Then, a + release branch was created and it was merged into main when the release + was finalized. Finally, main was tagged with version v1.0. diff --git a/src/docs/sphinx/dev_guide/index.rst b/src/docs/sphinx/dev_guide/index.rst index 37f4abf53b..7e75c32586 100644 --- a/src/docs/sphinx/dev_guide/index.rst +++ b/src/docs/sphinx/dev_guide/index.rst @@ -11,20 +11,23 @@ Developer Guide :hidden: :maxdepth: 2 - style_guide + codevelop docker_env - modern_cpp - testing + equation_solver + functional + gitflow_branching logging - profiling + macmini memory_checking + modern_cpp new_docker_image - tensor_dual - functional - codevelop + profiling + release + semantic_versioning state_manager - equation_solver - macmini + style_guide + tensor_dual + testing Developing a New Physics Module ------------------------------- diff --git a/src/docs/sphinx/dev_guide/release.rst b/src/docs/sphinx/dev_guide/release.rst new file mode 100644 index 0000000000..8f4a510d2b --- /dev/null +++ b/src/docs/sphinx/dev_guide/release.rst @@ -0,0 +1,267 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _release-label: + +******************************************* +Release Process +******************************************* + +The Smith team decides as a group when the code is ready for a release. +Typically, a release is done when we want to make changes available to users; +e.g., when some new functionality is sufficiently complete or we want users to +try something out and give us feedback early in the development process. A +release may also be done when some other development goal is reached. This +section describes how an Smith releases is done. The process is fairly +informal. However, we want to ensure that the software is in a robust and +stable state when a release is done. We follow the process described in this +section to avoid oversights and issues that we do not want to pass on to users. + +In the :ref:`gitflow-label` section, we noted that the **main branch +records the official release history of the project**. Specifically, +whenever, the main branch is changed, it is tagged with a new +version number. We use a git 'lightweight tag' for this purpose. Such +a tag is essentially a pointer to a specific commit on the main branch. + +When all pull requests intended to be included in a release have been merged +into the develop branch, we create a release candidate branch +**from the develop branch**. The release candidate branch is used to finalize +preparations for the release. At this point, the next release cycle begins and +work may continue on the develop branch. + +.. important:: No significant code development should performed on a release + candidate branch. Apart from finalizing release notes and other + documentation, **no code changes** are to be merged directly + into a release candidate branch. If a bug is found, it should be + fixed and merged into develop via a pull request. Then, the + change should be included in the release candidate branch by + merging develop into it. Changing code in a release candidate is + a rare occurrence since the develop branch should always be + passing CI tests. + +When a release candidate branch is ready, it will be merged into the +**main branch** and a release tag will be made. Then, the main branch is +merged into the develop branch so that changes made to finalize the release +are included there. + +Here are the steps we follow for an Smith release. + +1: Start Release Candidate Branch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a release candidate branch **off the develop branch** to initiate a +release. The name of a release branch should contain the associated release +version name. Typically, we use a name like v0.5.0-rc +(i.e., version 0.5.0 release candidate). See :ref:`semver-label` for a +description of how version numbers are chosen. + +2: Finalize the Release in the Release Candidate Branch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All changes to Smith related to finalizing the release documentation, as +opposed to source code changes, are done in the release candidate branch. +Typical changes include: + +#. Update the version information (major, minor, and patch version numbers) + near the top of the ``smith/cmake/SmithVersion.cmake`` file. + +#. Make any changes that are needed, for correctness and completeness, in the + section for the new release in the file ``smith/RELEASE-NOTES.md``. This + should not take much time as release notes should have been updated in + pull requests that have been merged into develop during regular development. + See :ref:`release-notes-label` for information about release notes. Add the + release version number and release date in the section heading and add a + link to the new version on GitHub at **the bottom of the file.** Please + follow the established formatting in the file. + +#. Update the mail map in ``smith/.mailmap``, if needed, by adding names and + emails of new contributors since the last release. + +#. Update the citations in ``smith/CITATION.cff`` by adding the names + of new LLNL contributors since the last release. + +#. Test the code by running it through all continuous integration tests + and builds. This will be done automatically when the release pull request is + made. All build configurations must compile properly and all tests must pass + before the pull request can be merged. + +#. Fix any issues discovered during final release testing in a pull request and + merge that into develop after it is approved and CI checks pass. Then, + merge develop into the release candidate branch, and re-run + appropriate tests to ensure issues are resolved. If a major bug is + discovered, and it requires significant code modifications to fix, + do not fix it on the release branch. `Create a new GitHub issue + `_ and note it in the ``known bugs`` + section of the release notes. Alternatively, if time permits, fix the + bug in a different branch and create a pull request as you would do during + regular development. After the bug is resolved and that pull request is + merged into develop, merge develop into the release candidate branch where + checks will run on that. + +#. Make sure all documentation (source code, user guides, etc.) is + updated and reviewed. This should not be a substantial undertaking as + most of this should have been done during the regular development cycle. + +.. important:: It is good practice to have everyone on the team review the + release notes to ensure that they are complete, correct, and + sufficiently descriptive so that users understand the content + of the release. **Please make sure the section for the new + release follows the same organization as in previous release + sections.** + +3: Create a Pull Request for the Release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a pull request to merge the release candidate branch into main after +all release preparation changes have been made. When the release candidate +branch is complete, reviewed and approved, it will be merged into main. + +Typically, when a release is being prepared it will have been months since the +previous release when the main branch was last changed. Thus, the *diff* between +branches that will appear in the pull request to merge the release candidate +into main will be large. Fortunately, most of those changes will have been +reviewed and merged into the develop branch and do not require additional +review. + +To make the review and approval process easier for the release candidate pull +request, it is helpful to create a companion pull request that shows **only +the changes made in the release candidate branch to finalize the release.** +Specifically, the companion pull request is made to merge the release +candidate branch into develop. This pull request will not be merged, but it +will be much easier since it will show only the changes made in the release +candidate that are not in the develop branch. + +To facilitate the review process, we cross reference the two pull requests +in their respective pull request descriptions. Suppose the pull request for +the release (to merge the release candidate into main) is #N and the +companion pull request (to merge the release candidate into develop) is #M. +In the description of pull request N, add a link to pull request M and a +comment to **review pull request M and approve pull request N.** In the +description of pull request M, add a link to pull request M and a statement +that it is the companion pull request for N, that it **should be reviewed but +not merged** and that pull request N should be approved as it will be merged +for the release. + +4: Merge Release Candidate +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Merge the release candidate branch into the main branch after it has been +approved and all CI checks have passed. Do not "squash merge" as it will make +the histories of main and develop branches disagree, and we want to preserve +the history. After merging, the release candidate branch can be deleted. + +5: Draft a GitHub Release +^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Draft a new Release on GitHub `_ + +#. Enter a Release title. We typically use titles of the following form *Smith-v0.3.1* + +#. Select **main** as the target branch to tag a release. + +#. Enter the release tag name, such as v0.5.0, and specify to create the tag + when the release is published. + +#. Copy and paste the information for the release from the + ``smith/RELEASE-NOTES.md`` into the release description + (omit any sections that are empty). + +#. Add a statement at the top of the release note, such as: + Please download the `Smith-*.tar.gz` tarball below, which includes all of the + submodules needed to build Smith. + +#. Click the checkbox at the bottom of the page that says "Set as the latest release". + +#. Publish the release. This will create a tag at the tip of the main + branch and add corresponding entry in the + `Releases section `_ + +.. note:: + + GitHub will add tarfile and zip archives consisting of the + source files for each release. However, these files do not include any + submodules. Consequently, a tarfile that includes all of the submodules is + generated manually in a separate step described below. + +6: Make Release Tarfile +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. After the release is published on GitHub, checkout the main branch locally + and run the command ``./scripts/make_release_tarball.sh`` + from the top level ``smith`` directory. This will generate a tarfile: for example, + ``Smith-v0.3.1.tar.gz``, consisting of the smith repo source. + +#. Attach the tarfiles for the corresponding release, by going to the + `GitHub Releases section `_ and + ``Edit`` the release created in step 5 above. Click ``Paste, drop, or click to add files`` + at the bottom of the release description section and select the + Smith release and data tarfiles created in the previous step. + +#. Click the ``Update release`` button. + +8: Merge Main to Develop +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a pull request to merge main into develop so that changes in the +release candidate branch are integrated into subsequent Smith development. +When approved, merge it. + + +.. _release-notes-label: + +******************************************* +Release Notes +******************************************* + +Smith release notes are maintained in a single file ``smith/RELEASE-NOTES.md``. +The release notes for the latest version are at the top of the file. +Notes for previous releases appear after that in descending version number +order. + +For each version, the release notes must contain the following information: + + * Smith version number and date of release + + * One or two sentence overview of release, including any major changes. + + * Release note items should be broken out into the following sections: + + * Added: Descriptions of new features + * Removed: Notable removed functionality + * Deprecated: Deprecated features that will be removed in a future release + * Changed: Enhancements or other changes to existing functionality + * Fixed: Major bug fixes + * Known bugs: Existing issues that are important for users to know about + +.. note:: Release notes for each Smith version should explain what changed in + that version of the software -- and nothing else!! + +Release notes are an important way to communicate software changes to users +(functionality enhancements, new features, bug fixes, etc.). Arguably, they +are the simplest and easiest way to do so. Each change listed in the release +notes should contain a clear, concise statement of the change. Items should +be ordered based on the impact to users (higher impact - first, lower impact +last). + +.. note:: When writing release notes, think about what users need to know and + what is of value to them. + +Release notes should summarize new developments and provide enough detail +for users to get a clear sense of what's new. They should be brief -- don't +make them overly verbose or detailed. Provide enough description for users +to understand a change, but no more than necessary. In other words, release +notes summarize major closed issues in a human-readable narrative. Direct +users to other documentation (user guides, software documentation, example +codes) for details and additional information. + +.. note:: Release notes should be updated as work is completed and reviewed + along with other documentation in a pull request. This is much + easier than attempting to compile release notes before a release + by looking at commit logs, etc. Preparing release notes as part + of the release process should take no more than one hour. + +Lastly, release notes provide an easy-to-find retrospective record of +progress for users and other stakeholders. They are useful for developers +and for project reporting and reviews. diff --git a/src/docs/sphinx/dev_guide/semantic_versioning.rst b/src/docs/sphinx/dev_guide/semantic_versioning.rst new file mode 100644 index 0000000000..709b58cd95 --- /dev/null +++ b/src/docs/sphinx/dev_guide/semantic_versioning.rst @@ -0,0 +1,74 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _semver-label: + +*********************** +Semantic Versioning +*********************** + +The Smith team uses the *semantic* versioning scheme for assigning +release numbers. Semantic versioning is a methodology for assigning version +numbers to software releases in a way that conveys specific meaning about +the code and modifications from version to version. +See `Semantic Versioning `_ for a more detailed description. + +============================ +Version Numbers and Meaning +============================ + +Semantic versioning is based on a three part version number `MM.mm.pp`: + + * `MM` is the *major* version number. It is incremented when an incompatible + API change is made. That is, the API changes in a way that may break code + using an earlier release of the software with a smaller major version + number. Following Gitflow (above), the major version number may be changed + when the develop branch is merged into the main branch. + * `mm` is the *minor* version number. It changes when functionality is + added that is backward-compatible. The API may grow to support new + functionality. However, the software will function the same as any + earlier release of the software with a smaller minor version number + when used through the intersection of two APIs. Following Gitflow (above), + the minor version number is always changed when the develop branch is + merged into the main branch, except possibly when the major version + is changed. + * `pp` is the *patch* version number. It changes when a bug fix is made that + is backward compatible. That is, such a bug fix is an internal + implementation change that fixes incorrect behavior. Following Gitflow + (above), the patch version number is always changed when a hotfix branch + is merged into main, or when develop is merged into main and the + changes only contain bug fixes. + +=========================================== +What Does a Change in Version Number Mean? +=========================================== + +A key consideration in meaning for these three version numbers is that +the software has a public API. Changes to the API or code functionality +are communicated by the way the version number is incremented. Some important +conventions followed when using semantic versioning are: + + * Once a version of the software is released, the contents of the release + *must not* change. If the software is modified, it *must* be released + as a new version. + * A major version number of zero (i.e., `0.mm.pp`) is considered initial + development where anything may change. The API is not considered stable. + * Version `1.0.0` defines the first stable public API. Version number + increments beyond this point depend on how the public API changes. + * When the software is changed so that any API functionality becomes + deprecated, the minor version number *must* be incremented. + * A pre-release version may be denoted by appending a hyphen and a series + of dot-separated identifiers after the patch version. For example, + `1.0.1-alpha`, `1.0.1-alpha.1`, `1.0.2-0.2.5`. + * Versions are compared using precedence that is calculated by separating + major, minor, patch, and pre-release identifiers in that order. Major, + minor, and patch numbers are compared numerically from left to right. For + example, 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and patch + numbers are equal, a pre-release version has lower precedence. For + example, 1.0.0-alpha < 1.0.0. + +By following these conventions, it is fairly easy to communicate intent of +version changes to users and it should be straightforward for users +to manage dependencies on Smith.