On Thu, Jan 9, 2014 at 1:53 PM, Paul A. Bristow
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