From 8aeb36200f14ea2aa1dacb65348090ddd50e7fed Mon Sep 17 00:00:00 2001 From: Randolph Settgast Date: Sat, 28 Nov 2020 09:29:35 -0800 Subject: [PATCH] release/0.2.x candidate (#1126) * add RELEASE file. Update Code release number * update git workflow documentation * Update RELEASE_NOTES.md * Update RELEASE * Update RELEASE_NOTES.md Co-authored-by: Sergey Klevtsov Co-authored-by: Francois Hamon Co-authored-by: Andrea Franceschini Co-authored-by: Francois Hamon Co-authored-by: Sergey Klevtsov Co-authored-by: Matteo Cusini <49037133+CusiniM@users.noreply.github.com> Co-authored-by: Yue Hao Co-authored-by: Nicola Castelletto <38361926+castelletto1@users.noreply.github.com> Co-authored-by: Joshua White Co-authored-by: Herve Gross <40979822+herve-gross@users.noreply.github.com> --- NOTICE | 2 +- README.md | 2 +- RELEASE | 13 + RELEASE_NOTES.md | 51 ++- .../Contributing/GitWorkflow.rst | 366 ++++++++++++++++-- .../Contributing/index_contributing.rst | 2 +- 6 files changed, 394 insertions(+), 42 deletions(-) create mode 100644 RELEASE diff --git a/NOTICE b/NOTICE index 0fa06cd5f1e..d4592e5b158 100644 --- a/NOTICE +++ b/NOTICE @@ -1,7 +1,7 @@ LAWRENCE LIVERMORE NATIONAL LABORATORY NOTICE --------------------------------------------- -LLNL-CODE-746361 +LLNL-CODE-812638 Portions of this work were produced under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344. diff --git a/README.md b/README.md index 8f8c368d07e..be5f0a15966 100644 --- a/README.md +++ b/README.md @@ -61,4 +61,4 @@ For acknowledgements, please read the [ACKNOWLEDGEMENTS](./ACKNOWLEDGEMENTS ) fi For notice, please read the [NOTICE](./NOTICE ) file. -`LLNL-Code-746361` `OCEC-18-021` +`LLNL-CODE-812638` `OCEC-18-021` diff --git a/RELEASE b/RELEASE new file mode 100644 index 00000000000..12b7d1242f7 --- /dev/null +++ b/RELEASE @@ -0,0 +1,13 @@ +******************************************************************************* + +GEOSX version 0.2.0 + + Copyright (c) 2018-2020 Lawrence Livermore National Security LLC + Copyright (c) 2018-2020 The Board of Trustees of the Leland Stanford Junior University + Copyright (c) 2018-2020 Total, S.A + Copyright (c) 2019- GEOSX Contributors + All rights reserved. See details in the file LICENSE. + +Unlimited Open Source - LGPL v2.1 Distribution +LLNL-CODE-812638 +OCEC-18-039 diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 3c32c99d9a9..c5312137a7e 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -19,7 +19,54 @@ Version v0.2.0 -- Release date 2020-06-20 ========================================== -Lots of stuff to fill in... +* Extensive updates to Data Repository +* Discretization + * Finite element interface + * Kernel launching interface looping abstraction + * Element formulations for 1st order: + * 8-node hexahedron + * 6-node wedge + * 5-node pyramid + * 4-node tetrahedron + * Cell-centered Finite Volume method with Two-point Flux Approximation (TPFA) + * Hybrid Finite Volume method with TPFA and quasi-TPFA inner products +* Physics Solvers + * Solid mechanics explicit on GPU, implicit assembly on GPU + * Single-phase flow (assembly on GPU) + * Classical FVM and Hybrid FVM formulations + * Porous matrix and DFM fracture flow + * Compositional multiphase flow (assembly on GPU) + * Fully implicit isothermal overall composition formulation + * Fluid constitutive models: + * Equation-of-state hydrocarbon compositional + * Three-phase extended black-oil + * Two-phase CO2-brine + * Multi-segmented wells for single phase and compositional multiphase flow (assembly on GPU) + * Surface Generation + * Topology change (legacy GEOS approach) +* Embedded Discrete Fractures + * Enriched finite element method for the discretization of the mechanics + * Piecewise constant displacement jump enrichment + * Hydrofracture solver (legacy GEOS approach) + * Small strain aligned contact using Lagrange multipliers + * Discrete fracture model using a low-order stabilized mixed finite element method + * Proppant Transport Solver + * FVM formulation + * Major physical processes modeled: + * Proppant-fluid slurry flow and multicomponent transport in fractures + * Proppant gravitational settling + * Proppant bed build-up and development space +* Mesh Structure + * Introduced the concept of extrinsic mesh data + * Fracture elements to represent FV cells in fractures +* VTK output +* Linear algebra interface layers for Hypre, Trilinos, Petsc + * Common interface for supported linear algebra packages + * Krylov solvers (CG, GMRES, BiCGSTAB) + * Preconditioners (algebraic multigrid, incomplete factorizations) + * Block matrix and vector support + * Serial and parallel direct solvers + Version v0.1.0 -- Release date 2018-02-15 ========================================== @@ -28,7 +75,7 @@ Initial Code Release containing: * Group * Wrapper * Input processing -* Physics Solver hierarcy +* Physics solver hierarchy * Solid Mechanics * Mesh data structure * NodeManager, EdgeManager, FaceManager, ElementManager diff --git a/src/docs/sphinx/developerGuide/Contributing/GitWorkflow.rst b/src/docs/sphinx/developerGuide/Contributing/GitWorkflow.rst index 8d04ec72bf5..987c12fc58b 100644 --- a/src/docs/sphinx/developerGuide/Contributing/GitWorkflow.rst +++ b/src/docs/sphinx/developerGuide/Contributing/GitWorkflow.rst @@ -5,10 +5,10 @@ Git Workflow ************************************** The GEOSX project is hosted on github `here `__. -For instuctions on how to clone and build GEOSX, please refer to the :ref:`GettingStartedWithGEOSX`. +For instructions on how to clone and build GEOSX, please refer to the :ref:`GettingStartedWithGEOSX`. Consider consulting `https://try.github.io/ `_ for practical references on how to use git. -Git credentials +Git Credentials ======================================= Those who want to contribute to GEOSX should setup SSH keys for authentication, and connect @@ -17,7 +17,7 @@ Before going further, you should `test your ssh connection `_ as an alternative. -Downloading the code +Downloading the Code ======================================= Once you have created an ``ssh-key`` and you have added it to your `Github` account you can download @@ -25,56 +25,325 @@ the code through SSH. .. code-block:: sh - git clone git@github.com:GEOSX/GEOSX.git - cd GEOSX + git clone git@github.com:GEOSX/GEOSX.git your_geosx_dir <--( last argument is the directory to + place the repository in) + cd your_geosx_dir git lfs install git submodule init git submodule update - cd .. If all goes well, you should have a complete copy of the GEOSX source at this point. The most common errors people encounter here have to do with Github not recognizing their authentication settings. -Working on the main code -======================================= +Branching Model +=============== +The current branching model used in GEOSX (starting with version 0.2) is essentially the +`Oneflow branching model and workflow `_ +with some modifications to the merging strategy, and the treatment of release +branches. +In GEOSX, the ``develop`` branch serves as the main branch in the ``Oneflow`` model. +The remaining branch types are described in the following subsections. + +.. note:: + The early commits in GEOSX (up to version 0.2) used a + `Gitflow `_ + approach for merging feature branches into develop. + This was done without cleaning the commit history in each feature + branch prior to the merge into develop, resulting in an overly verbose history. + Furthermore, as would be expected, having many active feature branches resulted + in a fairly wide/spaghetti history. + At some point in the development process, we chose to switch primarily to a + squash-merge approach which results in a linear develop history. + While this fixes the spaghetti history, we do potentially lose important + commit history during the development process. + Options for merging are discussed in the following sections. + +.. _Feature_Branches: + +Feature Branches +---------------- +New developments (new features or modifications to features) are branched off +of ``develop`` into a ``feature`` branch. +The naming of feature branches should follow ``feature/[developer]/[branch-description]`` +if you expect that only a single developer will contribute to the branch, +or ``feature/[branch-description]`` if you expect it will be a collaborative effort. +For example, if a developer named ``neo`` were to add or modify a code feature +expecting that he/she would be the only contributor, he/she would create a branch +using the following commands to create the local branch and push it to the remote +repository: + +.. code-block:: sh + + git checkout -b feature/neo/freeYourMind + git push -u origin feature/neo/freeYourMind + +However if the branch is a collaborative branch amongst many developers, the +appropriate commands would be: + +.. code-block:: sh + + git checkout -b feature/freeYourMind + git push -u origin feature/freeYourMind + +When ``feature`` branches are ready to be merged into ``develop``, a ``Pull Request`` +should be created to perform the review and merging process. + +An example lifecycle diagram for a feature branch: + +.. code-block:: sh + + create new feature branch: + git checkout -b feature/neo/freeYourMind + + A-------B-------C (develop) + \ + \ + BA (feature/neo/freeYourMind) + + Add commits to 'feature/neo/freeYourMind' and merge back into develop: + + A-------B--------C-------D--------E (develop) + \ / + \ / + BA----BB----BC (feature/neo/freeYourMind) + +See below for details about :ref:`Submitting_a_Pull_Request`. + +Bugfix Branches +--------------- +Bugfix branches are used to fix bugs that are present in the ``develop`` branch. +A similar naming convention to that of the ``feature`` branches is used, replacing +"feature" with "bugfix" (i.e. ``bugfix/neo/squashAgentSmith``). +Typically, bugfix branches are completed by a single contributor, but just as with +the ``feature`` branches, a collaborative effort may be required resulting a +dropping the developer name from the branch name. + +When ``bugfix`` branches are ready to be merged into ``develop``, a ``Pull Request`` +should be created to perform the review and merging process. +See below for details about :ref:`Submitting_a_Pull_Request`. + + +Release Branches +---------------- +When ``develop`` has progressed to a point where we would like to create a new +``release``, we will create a ``release`` branch with the name consisting +of ``major.minor.x`` number, where the ``x`` represents the sequence of patch tags that +will be applied to the branch. +For instance if we were releasing version ``1.2.0``, we would name the branch +``release/1.2.x``. +In contrast to the ``OneFlow`` approach, we do not delete the ``release`` branch. +Once the release candidate is ready, it is tagged and merged back into ``develop``. +From that point the ``release`` branch exists to provide a basis for maintaining +the major/minor release via the patching index. +Once the ``release/major.minor.x`` branch is tagged, it only exists as a starting point +for patches. +Each patch on the branch is tagged using an increment in the patch number, +resulting in a sequence of tags like ``release/1.2.0, release/1.2.1, release/1.2.2``, etc. + +.. note:: + + In our git workflow, we do not close the release loop by merging the final + release commit into ``develop``. + Once the initial ``release/x.y.z`` branch is tagged ``release/x.y.0`` and merged + into ``develop``, no further efforts are made to merge subsequent modifications + in the ``release`` branch into ``develop``. + +An example lifecycle diagram for a release branch: + +.. code-block:: sh + + A----B----C----D----E----F (develop) + \ / \ + \ / \ + BA--------BB EA (release/1.2.x) + (1.2.0) + +Hotfix Branches +--------------- +A ``hotfix`` branch fixes a bug in the ``release`` branch. +It uses the same naming convention as a ``bugfix`` branch. +The main difference with a ``bugfix`` branch is that the primary target branch is the +``release`` branch instead of ``develop``. +As a soft policy, merging a ``hotfix`` into a ``release`` branch should result in +a patch increment for the release sequence of tags. +So if a ``hotfix`` was merged into ``release/1.2.z`` with a most recent tag of +``1.2.1``, the merged commit would be tagged with ``1.2.2``. + +An example lifecycle diagram for release/hotfix branchs: + +.. code-block:: sh + + A----B----C----D----E----F (develop) + \ /| + \ / | + \ / | EAA---EAB (hotfix) + \ / | / \ + \ / |/ \ + BA---BB EA EB (release/1.2.x) + (1.2.0) (1.2.1) + + +In addition to merging into the ``release`` branch, the ``hotfix`` may also target +``develop`` if it is appropriate. +If the bug exists in ``develop`` and there are no plans to fix the bug prior +to the next ``major.minor`` release cycle, then the ``hotfix`` should be merged +into ``develop``. +As ``develop`` may have diverged significantly from the target ``release`` branch, +the ``hotfix`` branch may need further revisions for successful integration into +``develop``. +As such, the procedure for integration of a hotfix would be to create a new ``bugfix`` +branch that "cherry-picks" the ``hotfix`` commit/s used to patch ``release``, and +apply appropriate revisions for a successful merge into ``develop``. +For example if a ``hotfix`` was contained into commit ``BBB``, then the following +commands would create the appropriate ``bugfix`` branch: + +.. code-block:: sh -Once you have cloned the GEOSX repository, you can start developing by creating your -own branch. GEOSX branching and merging for development is a simplification of the the -`GitFlow `_ branching model. + git checkout develop + git checkout -b bugfix/neo/freeYourMind + git cherry-pick BBB + git push -u origin bugfix/neo/freeYourMind + +Additional commits to this ``bugfix`` branch may then be added prior to merging +into ``develop``. + +An example lifecycle diagram for release/hotfix/bugfix branchs: + +.. code-block:: sh + + A----B-----C-----D-----E-------F---G---H-- (develop) + \ /| \ / + \ / | FA---FB (bugfix/neo/freeYourMind) + \ / | / + \ / | EAA---EAB (hotfix) + \ / | / \ + \ / |/ \ + BA---BB EA EB (release/1.2.x) + (1.2.0) (1.2.1) + + +Some useful links for use of ``git cherry-pick`` are given here: + +`Documentation for git cherry-pick `_ + +`Explanation of git cherry-pick `_ + +`Example usage of git cherry-pick `_ + +Documentation Branches +---------------------- +A ``docs`` branch is focused on writing and improving the documentation for GEOSX. +The use of the ``docs`` branch name root applies to both sphinx documentation +and doxygen documentation. +The ``docs`` branch follows the same naming conventions as described in the :ref:`Feature_Branches` +section. +The html produced by a documentation branch should be proofread using sphinx/doxygen +prior to merging into ``develop``. + + +Keeping Your Branch Current +=========================== +Over the course of a long development effort in a single ``feature`` branch, a +developer may need to either merge ``develop`` into their ``feature`` branch, or rebase +their ``feature`` branch on ``develop``. +We do not have a mandate on how you keep your branch current, but we do have +guidelines on the branch history when merging your branch into ``develop``. +Typically, merging ``develop`` into your branch is the easiest approach, but will +lead to a complex relationship with ``develop`` with multiple interactions... which +can lead to a confusing history. +Conversely, rebasing your branch onto ``develop`` is more difficult, but will lead +to a linear history within the branch. +For a complex history, we will perform a squash merge into ``develop``, thereby +the work from the branch will appear as a single commit in ``develop``. +For clean branch histories where the individual commits are meaningful and should +be preserved, we have the option to perform a merge commit in with the PR is merged +into ``develop``, with the addition of a merge commit, thus maintaining the commit history. + + +Branching off of a Branch +=========================== +During the development processes, sometimes it is appropriate to create a branch +off of a branch. +For instance, if there is a large collaborative development effort on the branch +``feature/theMatrix``, and a developer would like to add a self-contained and easily +reviewable contribution to that effort, he/she should create a branch as follows: -In particular your branch name should follow the ``[purpose]/[developer]/[branch-description]`` -naming schema, where `purpose` is usually one of ``feature, bugfix, doc``, `developer` is -your chosen identifier (often simply your github username), and branch `branch-description` -is a short description of the purpose of the branch. +.. code-block:: sh -Create your own branch using the following command: + git checkout feature/theMatrix + git checkout -b feature/smith/dodgeBullets + git push -u origin feature/smith/dodgeBullets + +If ``feature/smith/dodgeBullets`` is intended to be merged into ``feature/theMatrix``, +and the commit history of ``feature/theMatrix`` is not changed via ``git rebase``, then +the process of merging the changes back into ``feature/theMatrix`` is fairly standard. + +However, if ``feature/theMatrix`` is merged into ``develop`` via a ``squash merge``, +and then ``smith`` would like to merge ``feature/smith/dodgeBullets`` into ``develop``, +there is a substantial problem due to the diverged history of the branches. +Specifically, ``feature/smith/dodgeBullets`` branched off a commit in ``feature/theMatrix`` +that does not exist in ``develop`` (because it was squash-merged). +For simplicity, let us assume that the commit hash that ``feature/smith/dodgeBullets`` +originated from is ``CC``, and that there were commits ``CA, CB, CC, CD`` in ``feature/theMatrix``. +When ``feature/theMatrix`` was squash-merged, all of the changes appear in ``develop`` as commit ``G``. +To further complicate the situation, perhaps a complex PR was merged after ``G``, resulting +in ``E`` on develop. +The situation is illustrated by: .. code-block:: sh - git checkout -b + A----B----C----D----E----F----G----E (develop) + \ / + CA---CB---CC---CD (feature/theMatrix) + \ + CCA--CCB--CCC (feature/smith/dodgeBullets) + +In order to successfully merge ``feature/smith/dodgeBullets`` into ``develop``, all +commits present in ``feature/smith/dodgeBullets`` after ``CC`` must be included, while discarding +``CA, CB``, which exist in ``feature/smith/dodgeBullets`` as part of its history, but not +in ``develop``. + +One "solution" is to perform a ``git rebase --onto`` of ``feature/smith/dodgeBullets`` onto +``develop``. +Specifically, we would like to rebase ``CCA, CCB, CCC`` onto `G`, and proceed with our +development of ``feature/smith/dodgeBullets``. +This would look like: + +.. code-block:: sh -For example, if you were going to work on a new physics solver, you might name your -branch `feature/yourName/xxx-physics-solver`. + git checkout develop + git pull + git checkout feature/smith/dodgeBullets + git rebase -onto G CC -You can now perform work on the newly created branch, ``add`` it and ``commit`` your -work. Once you have done so you can push your changes to the geosx repository and -set up an upstream branch to be tracked. +As should be apparent, we have specified the starting point as ``G``, and the point +at which we replay the commits in ``feature/smith/dodgeBullets`` as all commits +AFTER ``CC``. +The result is: .. code-block:: sh - git push --set-upstream origin + A----B----C----D----E----F----G----E (develop) + \ + CCA'--CCB'--CCC' (feature/smith/dodgeBullets) + +Now you may proceed with standard methods for keeping ``feature/smith/dodgeBullets`` +current with ``develop``. -Once you have created your branch and pushed to remote, you can now create a pull -request on github, to create a central place to review and discuss the ongoing work -on the branch. Creating a pull request early in the development process is prefered -as it allows for developers to collaborate on the branch more readily. +.. _Submitting_a_Pull_Request: Submitting a Pull Request ====================================== +Once you have created your branch and pushed changes to Github, you can create a +`Pull Request `_ on Github. +The PR creates a central place to review and discuss the ongoing work on the branch. +Creating a pull request early in the development process is preferred as it allows +for developers to collaborate on the branch more readily. -When initially creating a pull request (PR) on GitHub, create it is a draft PR while -work is ongoing and the PR isn't ready for testing, review, and merge consideration. +.. note:: + When initially creating a pull request (PR) on GitHub, always create it as a *draft* PR while + work is ongoing and the PR is not ready for testing, review, and merge consideration. When you create the initial draft PR, please ensure that you apply appropriate labels. Applying labels allows other developers to more quickly filter the live PRs and access @@ -82,8 +351,28 @@ those that are relevant to them. Always add the `new` label upon PR creation, as as to the appropriate `type`, `priority`, and `effort` labels. In addition, please also add any appropriate `flags`. -Note, if your branch and PR will resolve any open issues, be sure to `link` them to -the PR to ensure they are appropriate resolved once the PR is merged. + +.. note:: + If your branch and PR will resolve any open issues, be sure to `link` them to + the PR to ensure they are appropriately resolved once the PR is merged. + In order to `link` the issue to the PR for automatic resolution, you must use + one of the keywords followed by the issue number (e.g. resolves #1020) in either + the main description of the PR, or a commit message. + Entries in PR comments that are not the main description or a commit message + will be ignored, and the issue will not be automatically closed. + A complete list of keywords are: + + - close + - closes + - closed + - fix + - fixes + - fixed + - resolve + - resolves + - resolved + + For more details, see the `Github Documentation `_. Once you are satisfied with your work on the branch, you may promote the PR out of draft status, which will allow our integrated testing suite to execute on the PR branch @@ -93,9 +382,12 @@ Once the tests are passing -- or in some cases immediately -- add the `flag: rea label to the PR, and be sure to tag any relevant developers to review the PR. The PR *must* be approved by reviewers in order to be merged. -Note that commits are ``squashed`` whenever a pull request is merged into ``develop``. +Note that whenever a pull request is merged into ``develop``, commits are either +``squashed``, or preserved depending on the cleanliness of the history. +Keeping Submodules Current +======================================= Whenever you switch between branches locally, pull changes from ``origin`` and/or ``merge`` from the relevant branches, it is important to update the submodules to move the ``head`` to the proper ``commit``. @@ -107,7 +399,7 @@ move the ``head`` to the proper ``commit``. You may also wish to modify your `git pull` behavior to update your submodules recursively for you in one command, though you forfeit some control granularity to do so. The method for accomplishing this varies between git versions, but -as of git 2.15 you should be able to globaly configure git to accomplish this via: +as of git 2.15 you should be able to globally configure git to accomplish this via: .. code-block:: sh @@ -117,7 +409,7 @@ In some cases, code changes will require to rebaseline the ``Integrated Tests``. If that is the case, you will need to modify the ``integrated tests submodule``. Instructions on how to modify a submodule are presented in the following section. -Working on the submodules +Working on the Submodules ======================================= Sometimes it may be necessary to modify one of the submodules. In order to do so, @@ -152,12 +444,12 @@ create a pull request using the same process discussed above in :ref:`Submitting Resolving Submodule Changes In Primary Branch PRs ================================================= -When you conduct work on a submodule as described above during work on a primary GEOSX -branch which has a PR, the merging procedure requires that the submodule referenced +When you conduct work on a submodule during work on a primary GEOSX +branch with an open PR, the merging procedure requires that the submodule referenced by the GEOSX PR branch be consistent with the submodule in the main branch of the project. This is checked and enforced via TravisCI. -Thus in order to merge a PR that includes modifications to submodules, the various PRs for +Thus, in order to merge a PR that includes modifications to submodules, the various PRs for each repository should be staged and finalized, to the point they are all ready to be merged, with higher-level PRs in the merge hierarchy having the correct submodule references for the current main branch for their repository. diff --git a/src/docs/sphinx/developerGuide/Contributing/index_contributing.rst b/src/docs/sphinx/developerGuide/Contributing/index_contributing.rst index 0c85f5d54f3..5783454999e 100644 --- a/src/docs/sphinx/developerGuide/Contributing/index_contributing.rst +++ b/src/docs/sphinx/developerGuide/Contributing/index_contributing.rst @@ -3,7 +3,7 @@ Contributing ############################################################################### .. toctree:: - :maxdepth: 2 + :maxdepth: 3 CodeStyle.rst