diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index 278b9e4bfd..315bacac69 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -141,7 +141,8 @@ unrelated feature, you should switch branches! Committing changes to the *develop*, *release*, or *stable* branches is strongly discouraged. While it may be convenient initially, it will create more work in the long run. Various texts and tutorials - on using git effectively discuss the motivation for this. + on using git effectively discuss the motivation for using feature + branches instead. **After changes are made** diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index 7ad6ca18c1..a5dc19fe79 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -28,8 +28,9 @@ provides `limited support for subversion clients `_. You can follow the LAMMPS development on 3 different git branches: -* **stable** : this branch is updated with every stable release; - updates are always "fast forward" merges from *develop* +* **stable** : this branch is updated from the *release* branch with + every stable release version and also has selected bug fixes and updates + back-ported from the *develop* branch * **release** : this branch is updated with every patch release; updates are always "fast forward" merges from *develop* * **develop** : this branch follows the ongoing development and @@ -47,20 +48,22 @@ your machine and "release" is one of the 3 branches listed above. (Note that you actually download all 3 branches; you can switch between them at any time using "git checkout ".) -.. note:: +.. admonition:: Saving time and disk space when using ``git clone`` The complete git history of the LAMMPS project is quite large because it contains the entire commit history of the project since fall 2006, - which includes the time when LAMMPS was managed with subversion. This - also includes commits that have added and removed some large files - (mostly by accident). If you do not need access to the entire commit - history, you can speed up the "cloning" process and reduce local disk - space requirements by using the *--depth* git command line flag thus - create a "shallow clone" of the repository that contains only a - subset of the git history. Using a depth of 1000 is usually sufficient - to include the head commits of the *develop* and the *release* branches. - To include the head commit of the *stable* branch you may need a depth - of up to 10000. + which includes the time when LAMMPS was managed with subversion. + This includes a few commits that have added and removed some large + files (mostly by accident). If you do not need access to the entire + commit history (most people don't), you can speed up the "cloning" + process and reduce local disk space requirements by using the + *--depth* git command line flag. That will create a "shallow clone" + of the repository containing only a subset of the git history. Using + a depth of 1000 is usually sufficient to include the head commits of + the *develop* and the *release* branches. To include the head commit + of the *stable* branch you may need a depth of up to 10000. If you + later need more of the git history, you can always convert the + shallow clone into a "full clone". Once the command completes, your directory will contain the same files as if you unpacked a current LAMMPS tarball, with the exception, that diff --git a/doc/src/Manual_version.rst b/doc/src/Manual_version.rst index b705ce8c4a..78ed61cd7c 100644 --- a/doc/src/Manual_version.rst +++ b/doc/src/Manual_version.rst @@ -10,23 +10,31 @@ Whenever we fix a bug or update or add a feature, it will be merged into the *develop* branch of the git repository. When a sufficient number of changes have accumulated *and* the software passes a set of automated tests, we release it in the next *patch* release, which are made every -few weeks. Info on patch releases are on `this website page +few weeks. The *release* branch of the git repository is updated with +every such release. Info on patch releases are on `this website page `_. -Once or twice a year, only bug fixes and small, non-intrusive changes are -included for a period of time, and the code is subjected to more detailed +Once or twice a year, we apply only bug fixes and small, non-intrusive +changes to the *develop* branch and the code is subjected to more detailed and thorough testing than the default automated testing. The latest -patch release after such a period is then labeled as a *stable* version. +patch release after such a period is then also labeled as a *stable* version +and the *stable* branch is updated with it. Between stable releases +we occasionally release some updates to the stable release containing +only bug fixes and updates back-ported from *develop* but no new features +and update the *stable* branch accordingly. -Each version of LAMMPS contains all the features and bug-fixes up to -and including its version date. +Each version of LAMMPS contains all the documented features up to and +including its version date. The version date is printed to the screen and logfile every time you run LAMMPS. It is also in the file src/version.h and in the LAMMPS directory name created when you unpack a tarball. And it is on the first page of the :doc:`manual `. -* If you browse the HTML pages on the LAMMPS WWW site, they always - describe the most current patch release of LAMMPS. +* If you browse the HTML pages on the LAMMPS WWW site, they will by + default describe the most current patch release version of LAMMPS. + In the navigation bar on the bottom left, there is the option to + view instead the documentation for the most recent *stable* version + or the latest version from the current development branch. * If you browse the HTML pages included in your tarball, they describe the version you have, which may be older.