boost/website-v2-docs
2
0
Fork 0
mirror of https://github.com/boostorg/website-v2-docs.git synced 2026-01-19 04:42:17 +00:00
Code Issues Projects Releases Wiki Activity

Super-project section

Browse Source 
fix #154
This commit is contained in:
Peter Turcan
2023-11-24 15:22:59 -08:00
committed by GitHub
parent ae47b04b24
commit 9b60d2a669
5 changed files with 552 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
contributor-guide/modules/ROOT/nav.adoc
View File

@@ -33,6 +33,12 @@
** xref:testing/continuous-integration.adoc[]
** xref:testing/fuzzing.adoc[]
* The Super-project
** xref:superproject/overview.adoc[]
** xref:superproject/getting-started.adoc[]
** xref:superproject/library-maintenance.adoc[]
** xref:superproject/library-workflow.adoc[]
* Documentation
** xref:docs/documentation-guidelines.adoc[]
** xref:docs/documentation-components.adoc[]

128
contributor-guide/modules/ROOT/pages/superproject/getting-started.adoc Normal file
View File

@@ -0,0 +1,128 @@
= Getting Started with the Super-project
:navtitle: Getting Started
Boost libraries reside in subdirectories under the `libs` directory. For example, the contents of the boost:filesystem[] library are in `libs/filesystem.` This includes the build scripts (in l`ibs/filesystem/build`), the source files (in `libs/filesystem/src`), the tests (in `libs/filesystem/test`), the documentation (in `libs/filesystem/doc`), and so on.
In the past, when Boost used SVN as its version control system, the header files were an exception. The header files of all libraries resided in the `boost` subdirectory, and it wasn't possible to accurately determine which header belonged to which library.
When Boost moved to Git for version control, header files were moved to their corresponding libraries, into an include subdirectory. The header files of boost:filesystem[] are now in `libs/filesystem/include`.
For compatibility, `boost` is now a "virtual" directory, containing links to the headers. It's maintained automatically by https://www.bfgroup.xyz/b2/[B2]. The command `b2` creates or recreates the contents of the `boost` directory.
This structure allows us to determine that, when faced with an `#include <boost/filesystem.hpp>` directive, that this header is part of boost:filesystem[], and that therefore, the current library being scanned depends on boost:filesystem[].
Note:: Unfortunately, Boost releases do not have this structure. For backward compatibility, they have an old-style boost directory containing all header files, whereas the per-library include subdirectories are missing.
== Clone and Install the Super-project
To work within the Super-project, you will have to clone the Boost Git repository. To do that, execute the following command:
[source, bash]
----
git clone https://github.com/boostorg/boost.git boost
----
This will download the Super-project (the master project, without any libraries) and place it into the subdirectory `boost` of the current directory. To override the directory name, pass it as a second argument instead of boost:
[source, bash]
----
git clone https://github.com/boostorg/boost.git mydir
----
You can now `cd` into the newly created directory with `cd mydir`. This directory is called the "Boost root". All of the commands below assume that it is the current directory.
The above `git clone` commands download the default branch of the Boost Git repository, which is `master`. This is the current stable version of Boost. To verify this, issue the command `git status` from the Boost root. This will output
[source, bash]
----
# On branch master
nothing to commit, working directory clean
----
To download a specific release instead, such as 1.58.0, issue the following command after `git clone`, from the Boost root:
[source, bash]
----
git checkout boost-1.58.0
----
`git status` will now say"
[source, bash]
----
# HEAD detached at boost-1.58.0
nothing to commit, working directory clean
----
Then, download all the libraries:
[source, bash]
----
git submodule update --init
----
This step will take a while.
If all goes well, you will now have the complete contents of Boost's latest `master` branch (if you didn't checkout a specific release by name) or the corresponding Boost release (if you did).
You can switch between the `master` branch, the `develop` branch, and a release, by issuing the following commands:
For the `master` branch:
[source, bash]
----
git checkout master
git pull
git submodule update --init
----
Note:: `git pull` updates your local copy of the `master` branch from the server, in case it has changed since your initial checkout.
For the `develop` branch:
[source, bash]
----
git checkout develop
git pull
git submodule update --init
----
For the boost-1.58.0 release:
[source, bash]
----
git checkout boost-1.58.0
git submodule update --init
----
For the boost-1.57.0 release:
[source, bash]
----
git checkout boost-1.57.0
git submodule update --init
----
Note:: While the initial `git submodule update` is quite slow, as it needs to download all the libraries, the subsequent invocations are a lot faster.
Also note that if a new Boost library (`libs/convert`, for example) is present in, say, `master`, and you have it checked out, when you later switch to `boost-1.58.0`, where this library doesn't exist, Git will not delete `libs/convert`. In this case, git status will output
[source, bash]
----
# HEAD detached at boost-1.58.0
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# libs/convert/
nothing added to commit but untracked files present (use "git add" to track)
----
and you will have to remove `libs/convert` by hand.
Now, you have successfully installed the Super-project.
== See Also
* xref:superproject/overview.adoc[]

279
contributor-guide/modules/ROOT/pages/superproject/library-maintenance.adoc Normal file
View File

@@ -0,0 +1,279 @@
= Getting Started with Super-project Library Maintenance
:navtitle: Library Maintenance
This page briefly sketches the mechanics of maintaining a Boost library using Git. The intended audience is developers getting started with the maintenance of an existing Super-project library.
This page is intended to get you started only; it does not provide in-depth coverage. See links below for that.
Illustrations of how to perform various actions are given using the Git command line client.
== The Big Picture
Library maintenance occurs in the context of how Boost repositories are organized. Study the xref:superproject/overview.adoc[] before continuing, since a Boost developer needs to be familiar with how Boost organizes its repositories.
The examples given on this page follow Boost recommended workflow practices, but keep workflow discussion simple for this introduction. To better understand workflow recommendations and rationale before continuing, read xref:superproject/library-workflow.adoc[].
== Prerequisites
. A recent release of the Git command line client installed.
. A https://github.com/[GitHub] account.
. A pass:[C++] compiler and development environment installed and working smoothly.
. The Super-project installed, as described in xref:superproject/getting-started.adoc[].
. `b2` in your path. That allows the command line examples given here to work as shown on both Windows and POSIX-like systems.
== Typical Maintenance Tasks
=== Getting Ready to Work on a Library
The preferred environment library maintenance is to checkout the library's `develop` branch, or some other development branch, while other Boost libraries are as defined by the Super-project `master` branch. This causes local tests of your library to run against `master` for other Boost libraries at the point in time referenced by the Super-project.
This is a more realistic test environment in than testing against the possibly unstable `develop` branch of other Boost libraries or against the `master` branch of other libraries at a different point in time than that referenced by the Super-project. Robert Ramey has advocated this approach to testing for years, and the Super-project makes this approach relatively easy and fast.
Note:: The following examples assume you have installed the Super-project to a folder called `boost-root`.
[source, bash]
----
cd boost-root
git checkout master
git pull
git submodule update
----
The `git submodule update`` will fail if it would result in uncommitted changes being overwritten.
The `git submodule update` may switch submodules back to the detached state, depending on the working copy's exact situation.
See <<Effects of `git submodule update`>> for details.
To get more information about a submodule:
[source, bash]
----
cd boost-root
git submodule summary
----
If for some reason you wanted to test against the current head of master for all libraries, disregarding the Super-project state, the `git submodule update` command would be changed to:
[source, bash]
----
git submodule foreach --recursive "git checkout master; git pull"
----
If modules are added, these should be added to your project too, which is not done by the commands above. Run:
[source, bash]
----
git submodule update --init
----
Note that if you use the `--init` option, the already-initialized submodules will not be updated. You might have to run the command without `--init` afterwards.
=== Check out the Development Branch of your Library
You can see what branch `mylib` is currently on like this:
[source, bash]
----
cd boost-root/libs/mylib
git branch
----
Then if you need to change the branch to a development branch such as `develop`, do this:
[source, bash]
----
cd boost-root/libs/mylib
git checkout develop
----
You only have to do that once; your local repo working copy will sit on the branch until it is explicitly changed by a command you give.
Of course, you don't have to change the directory before every command, and from here on this tutorial will assume the directory has not been changed since the prior example.
If there is any possibility the branch head content in the public upstream repo has changed, you also will want to update content:
[source, bash]
----
cd boost-root/libs/mylib
git pull
----
From this point on, it is assumed you have already done a `cd boost-root/libs/mylib`.
=== Testing Locally
Unless you are 100% sure of the state of your library's regression tests, it is a good idea to run the regression tests before making any changes to the library:
[source, bash]
----
pushd test
b2
popd
----
=== Checking Status
Before making changes, it is a good idea to check status. Here is what that looks like on Windows; the message you get may vary somewhat:
[source, bash]
----
>git status
# On branch develop
nothing to commit, working directory clean
----
=== Fix a Simple Bug Directly on `develop`
For simple bugs, particularly in projects with a single maintainer, it is common practice to fix bugs directly in the `develop` branch. Creating a test case with your favorite editor, testing the test case, fixing the bug, testing the fix, and then iterating if necessary is no different than with any programming environment.
Once the fix is complete, you then commit the fix locally and push from your local repo up to your public `boostorg` repo on GitHub. These same commands would be used for any Git project, so hopefully you are already somewhat familiar with them:
[source, bash]
----
cd boost-root/libs/mylib
git commit -a -m "my bug fix"
git push
----
There are some significant disadvantages to this simple approach:
- The fix is now made to `develop` but you must remember to merge it to a release branch or directly to `master`. It is very easy to forget to do that merge, particularly if this is a mature library you are not working with very often.
- Users who need the bug fix right away are forced to jump through hoops to retrieve the fix from `develop`.
Putting out a point release solves both of those problems. Read on...
=== Fix a Bug using a Hot-fix Branch
Fixing a bug directly on the `develop` branch is fine, if that's the library's policy, but if the bug is messy, multiple maintainers are involved, interruptions are expected, or other complexities are present, then it is better practice to work on the bug in a separate branch. And doing that on a hot-fix branch solves the problems mentioned at the end of the prior section.
The operational distinction between a bug-fix branch and a hot-fix branch is that a bug-fix branch is branched from `develop` and then at completion merged back to `develop`, while a hot-fix branch is branched from `master` and then at completion is merged to both `master` and `develop`. With either approach, the branch is deleted after it has been merged.
[source, bash]
----
git checkout master
git checkout -b hotfix/complex-boo-boo
----
This creates the branch `hotfix/complex-boo-boo`, and switches to it. Incidentally, `hotfix/` is part of the name, not a directory specifier. The new branch is based on branch `master` because the working copy was on branch `master` at the time of the branch.
Since the bug is complex, it may take some time to fix and may go through several cycles of fixes, tests, and commits.
Once the bug is fixed and a final commit is done, then it is time to merge the `hotfix/complex-boo-boo` branch into `master` and `develop`:
[source, bash]
----
git checkout master
git merge hotfix/complex-boo-boo
git push
git checkout develop
git merge hotfix/complex-boo-boo
git push
git branch -d hotfix/complex-boo-boo
----
=== Start Work on a New Feature
Developers are encouraged to create a (possibly private) branch to work on new features, even simple ones, since development of new features on the `develop` branch might leave it unstable for longer that expected. Using the Git Flow convention, the branch will be named `feature/add-checksum-option`.
[source, bash]
----
git checkout develop
git checkout -b feature/add-checksum-option
----
When you create the branch, or perhaps later, you may decide the branch should be public (i.e. be present in the library's public `boostorg` repo) so that you can share the branch with others or just to back it up. If so, set that up by running:
[source, bash]
----
git push --set-upstream origin feature/add-checksum-option
----
Whether or not `--set-upstream origin bugfix/complex-boo-boo` is actually needed depends on the `branch.autosetupmerge` configuration variable that isn't discussed here. If you don't supply `--set-upstream origin bugfix/complex-boo-boo` on your first push and it turns out to be needed, you will get an error message explaining that.
The usual cycle of coding, testing, commits, and pushes (if public) then begins. If other work needs to be done, a stash or commit may be done to save work-in-progress, and the working copy switched to another branch for awhile. If significant fixes or other enhancements have been made to `develop` over time, it may be useful to merge `develop` into the feature branch so that the eventual merge back to `develop` has less conflicts. Here is how to merge from `develop` to `feature/add-checksum-option`:
[source, bash]
----
git checkout feature/add-checksum-option
git merge develop
----
=== Lightweight Library Release
Small, simple libraries and simple releases just merge the development branch, such as `develop`, into `master`, and test like this:
[source, bash]
----
git checkout master
git merge --no-ff develop
pushd test
b2
popd
----
Warning:: If there are any test failures, correct the problem, retest, and commit the fixes before proceeding with the release.
If there are no test failures, tag for release and declare victory:
[source, bash]
----
git push # push merge results
git tag -a -m "tag for release" mylib-2014-06-02
git push origin mylib-2014-06-02 # push specific tag to avoid pushing all local tags
----
See xref:superproject/library-workflow.adoc[] for release tag naming conventions.
=== Heavyweight Library Release
Large, complex libraries, particularly those with multiple developers working in parallel, need to use a release procedure that scales up better than the lightweight procedure. The Git Flow approach is recommended. Find out more at xref:superproject/library-workflow.adoc[] and be sure to study the examples given in https://nvie.com/posts/a-successful-git-branching-model/[Vincent Driessen's original blog post].
== Effects of `git submodule update`
The following table, based on actual tests run using git version `1.8.4.msysgit.0`, shows the effects on a submodule of:
```
cd boost-root
git checkout master
git pull
git submodule update
```
[cols="1,1,2,2",options="header",stripes=even,frame=none]
|===
| *Submodule Branch* | *Submodule Contents* | *Submodule relative to Super-project* | *Effects on Submodule*
| Detached | Unmodified | Up-to-date | None
| Detached | Unmodified | Behind | `git pull`
| Detached | Uncommitted change| Up-to-date | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA...) in submodule path '...'
| Detached | Uncommitted change| Behind | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA ...) in submodule path '...'
| Detached | Committed change | Up-to-date | `git checkout --detach`
| Detached | Committed change | Behind | `git checkout --detach`; `git pull`
| `master` | Unmodified | Up-to-date | `git checkout --detach`
| `master` | Unmodified | Behind | `git pull` (but no detach)
| `master` | Uncommitted change| Up-to-date | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA...) in submodule path '...'
| `master` | Uncommitted change| Behind | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA...) in submodule path '...'
| `master` | Committed change | Up-to-date | `git checkout --detach`
| `master` | Committed change | Behind | `git checkout --detach`; `git pull`
| `develop` | Unmodified | Up-to-date | `git checkout --detach`
| `develop` | Unmodified | Behind | `git checkout --detach`; `git pull`
| `develop` | Uncommitted change| Up-to-date | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA...) in submodule path '...'
| `develop` | Uncommitted change| Behind | error: Your local changes to the following files would be overwritten by checkout: ... Please, commit your changes or stash them before you can switch branches. Aborting Unable to checkout (SHA...) in submodule path '...'
| `develop` | Committed change | Up-to-date | `git checkout --detach`
| `develop` | Committed change | Behind | `git checkout --detach`; `git pull`
|===
Note:: Be aware that `git checkout --detach;` and `git pull` are used as shorthand to describe the apparent effects. The actual git implementation may differ.
== Acknowledgements
Beman Dawes created and maintained this page. The content has been revised many times based on comments and list postings from Andrey Semashev, John Maddock, Daniel James, Michael Cox, Pete Dimov, Edward Diener, Bjørn Roald, Klaim - Joël Lamotte, Peter A. Bigot, and others.
== See Also
* xref:superproject/overview.adoc[]

72
contributor-guide/modules/ROOT/pages/superproject/library-workflow.adoc Normal file
View File

@@ -0,0 +1,72 @@
= Super-project Library Workflow
:navtitle: Library Workflow
Workflow is the term used to describe the steps a Boost library developer follows to create, maintain, and release a library. The workflow presented here is designed for Boost's individual libraries. The workflow for the Super-project may differ.
== Git Flow
The workflow model Boost recommends is called Git Flow. It was introduced as a simple https://nvie.com/posts/a-successful-git-branching-model/[blog posting by Vincent Driessen] on January 5th, 2010, that went viral and has become a widely used software engineering practice.
This workflow has arguably become so successful because it scales well from very small to very large projects, and that's one of the reasons it is recommended (but not required) for Boost libraries.
- An unusually simple, single developer library would have only the permanent `develop` and `master` branches that are required for all Boost libraries.
- A more typical library would occasionally add temporary feature branches, either private or public. Feature branch names follow the `feature/x` model, where `x` names the specific feature being developed.
- A larger library, particularly if it has multiple developers, would always have some active public feature branches, and at least occasionally employ release staging branches and hotfix branches. Individual developers would often use private branches.
Many Git Flow model diagrams are available online - print one out and hang it on your wall!
== Command Line Tools
For those who use Git from the command line, https://github.com/nvie/gitflow[git-flow command line tools] are available to automate common operations. See https://github.com/nvie/gitflow/wiki[git-flow wiki] for more information, including installation instructions for various platforms.
== Branch Names
All Boost libraries are required to have two branches:
. `master` is always the library's latest release. It should always be stable.
. `develop` is always the main development branch. Whether it is always stable or not is up to the individual library.
These branches are required so that Boost release management and other scripts know the branch names.
While Boost libraries are not required to use the following branches, these naming conventions are recommended if the branches are present.
- `feature/descriptive-name` for feature branches. For example, `feature/add-roman-numeral-math`.
- `bugfix/descriptive-name` for problem fix branches of develop that will be merged back to develop after the fix. For example, `bugfix/ticket-1234-error-msg-not-clear`.
- `hotfix/descriptive-name` for problem fix branches of master that will be merged back to master and also to develop after the fix. For example, `hotfix/ticket-5678-crash-if-result-negative`.
- `release/n.n.n` for release staging branches. For example, `release/1.56.2`.
== Release Names
Individual Boost libraries are free to choose their own release numbers, and these library release numbers are normally unrelated to the release numbers for the Super-project. The recommended release naming convention is the traditional three unsigned integers separated by periods (for example: 1.2.3) where:
- The first integer is the major version number, with each major version, with 0 being used for initial development and 1 for the first production-usable version. A change in version number is recommended when there are breaking changes.
- The middle integer is the release number, reset to 0 with each version update and otherwise increasing monotonically.
- The last integer is the patch level, reset to 0 with each revision and otherwise increasing monotonically. A patch level greater than 1 indicates a so-called point releases, normally containing bug fixes but not new features.
== Release Tags
A release tag is usually the library name, a hyphen, the release number, and then possibly "-beta#" or "-rc#" if applicable. Thus the second release candidate for boost:timer[] release 1.2.3 would be "timer-1.2.3-rc2".
Peter A. Bigot suggested library name prefixes for tags to avoid tag namespace pollution. Without the prefix, local tags could be overwritten.
Libraries choose their own release numbers. A simple library that does not require a complex release numbering convention might just use the date, such as "system-2014-06-02".
== Rationale for Choice of Git Flow
Git Flow scales well from very small to very large projects. The same overall workflow model serves the whole spectrum of Boost libraries, even though the details differ.
Git Flow has become widely known and widely used. Boost doesn't have to pioneer a new workflow.
== Aside: Deleting Merged Branches
The usual culture with Git is to delete feature branches as soon as they are merged to some other branch, and is followed by Git Flow. This approach is also recommended for Boost developers. After all, the merged-to branch keeps the commit history alive and there's no longer any need to keep the old label around. If you delete a branch without merging it, of course, any content and commit history exclusive to that branch is lost.
== See Also
* xref:superproject/overview.adoc[]

67
contributor-guide/modules/ROOT/pages/superproject/overview.adoc Normal file
View File

@@ -0,0 +1,67 @@
= Super-project Layout
:navtitle: Super-project Layout
This section covers the organization of the Boost pass:[C++] Libraries into separate, independently developable modules, each residing in its own repository, to facilitate development, integration, and selective inclusion of individual libraries.
This section provides an overview of how the Super-project is organized.
== Overall Organization
The Boost Super-project consists of separate projects for each individual library. In terms of Git, the Super-project treats the individual libraries as _submodules_.
All public repositories are hosted at https://github.com/boostorg[GitHub boostorg].
Releases of individual libraries occur asynchronously from releases of the Super-project.
== Repositories
- The Super-project has its own public repository within `boostorg`. It treats each individual library as a submodule, i.e. a link to a particular release in the library's public GitHub repository. The Super-project is maintained by the Boost release managers, and most library developers do not have write access.
- Each individual library has its own public repository within `boostorg`. For example, boost:config[] has a public repository here. The maintainer of a library decides who has write access to the public repository. Release managers and their helpers also have write access for administrative purposes.
- As with any Git project, a library's developers do day-to-day work using private repositories on their local machines. When they push changes from these local private repositories up to the library's public repository is up to them, as is when the library issues releases. As usual with Git, the local repositories may have private branches that are never pushed to the public repository.
- Libraries are required to follow certain naming conventions for branches and directories, so that both humans and automatic test and management tools know where to find commonly referenced components. But beyond those requirements, each library is free to use whatever branch and directory strategies they wish.
== Branches
Boost requires all libraries have at least the two branches `master` and `develop`.
Releases for both the Super-project and individual libraries are always on branch `master`. `master` in the library's `boostorg` public repo should be stable at all times, so should only be pushed to the library's public repository when it is stable and ready to ship.
Branch `develop` is the main development branch. Whether or not `develop` is stable in the library's public `boostorg` repository is up to the library maintainer.
Additional branches, if any, are up to the library maintainer. See <<Git Flow for Workflow>>.
== Directory Structure
Your library's directory structure conforms to Boost directory structure conventions, so both users and automatic processes can find header files, test files, build configurations, and the like. Beyond the conventions, your library's directory structure is up to you.
The Super-project header files are placed in an `include/boost` directory hierarchy within the library's top-level directory. Here is what a very simple header-only library named `simple` would look like:
[source, bash]
----
simple
include
boost
simple
twice.hpp
test
twice_test.cpp
Jamfile.v2
index.html
----
Note:: The sub-directory hierarchy `include/boost/...` (where `...` represents the library's directories and header files) ensures that the library is entirely self-contained within the top-level directory.
A real library would also have additional sub-directories such as `doc`, `example`, and `src`, as described in the directory conventions, but they are left out of simple for the sake of brevity.
== Git Flow for Workflow
Boost recommends, but does not require, the approach to library workflow that has come to be known as Git Flow. For more about how this applies to Boost libraries, see xref:superproject/library-workflow.adoc[].
== See Also
** xref:superproject/getting-started.adoc[]
** https://www.bfgroup.xyz/b2/[B2]
** xref:version-control.adoc[]