Re: [boost] Fumbling with modular Boost and GIT

Subject: Re: [boost] Fumbling with modular Boost and GIT
From: Beman Dawes (bdawes_at_[hidden])
Date: 2014-01-10 08:59:15

On Thu, Jan 9, 2014 at 1:53 PM, Paul A. Bristow <pbristow_at_[hidden]>wrote:

> I have recently been fumbling with Modular Boost to do some routine
> maintenance and update of
> documentation on Boost.Math, with generally most unhappy results.
>
> Although this is partly from my general modest familiarity with GIT, I
> feel that the documentation
> of the process of doing things is woefully thin.  There are far too many
> vital details assumed or
> unsaid.
>

The intent of the documentation is to quickly get developers started with
the specifics of Boost's use of Git in the modular (i.e. submodule)
environment.

The intent of the documentation is not to teach how to use Git or
TortoiseGit. There is a vast amount of high quality Git documentation,
tutorials, examples, answers to question, and so forth already available on
the web in both text and video form.

An effective, easy, and low-stress way to learn about Git is to set up a
GitHub account and create an experimental repository or two. Add some
files, and perform common operations (clone, add, remove, commit, push,
pull, branch, checkout, merge). This learning strategy works for both
command line and GUI clients. If you get totally confused, just blow the
local repo away and re-clone. Or blow the remote repo away and start over.
You can keep a clone of the initialized state handy to make recreation
easy. GitHub makes the mechanics of all this really easy.

The submodule environment steepens the learning curve significantly. So get
comfortable with non-submodule projects before moving on to submodule
projects such as Boost.

As of version 1.8.6.0, TortoiseGit is still failing on critical submodule
operations, so at least some Boost repo operations have to be done from the
command line. The TortoiseGit folks seem to be treating the bug as high
priority, so hopefully that will change soon. I will try to add some
additional TGit screenshots.

>
> I'm posting this in the hope that someone will produce a fully documented
> and illustrated
> blow-by-blow (preferably using Tortoise GIT and including its displays)
> description of how to work
> cooperatively on the develop branch, and a specific library development
> sub-branch.
>
> This should cover (at least) getting changes to headers in /boost and
> /libs made by others, making a
> change to a header file, making a change to tests, testing it using an
> IDE, and making a change to
> an example (containing some embedded Quickbook) in and IDE and running it,
>  and to changing
> Quickbook files in the /library/doc folder, and finally pushing.
>

Just like with SVN, the Git procedures are the same regardless of the type
of file or its location. If you are running into a specific problem, please
ask for help. I'm trying to monitor the help requests for indications of
need for git doc improvements.

>
> And now, for a change, I'm off for a little quiet alligator wrestling ;-)
>

I live in Florida nowadays, and have a neighbor who is a park ranger and
claims alligator wrestling is fun:-)

HTH,

--Beman