Getting Started with Modular Boost Library Maintenance
I've been pecking away at "Getting Started with Modular Boost Library Maintenance". See https://svn.boost.org/trac/boost/wiki/StartModMaint I'd appreciate comments and corrections. One of the questions that came up was how to number releases for individual libraries. Say Boost.System wants to do a release before the next full Boost release ships. What do I call it? How do I document it? How do I tag it? Strawman proposal ------------------------ * Call it "Boost.System 1.55.1 Point Release". * Document it via the "readme" file that GitHub pesters you to add. Contents would give the title of the release and the release notes. * Create a gh-pages branch with the same release notice. * Tag it 1.55.1 Comments? --Beman
Le 10/12/13 17:41, Beman Dawes a écrit :
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
See https://svn.boost.org/trac/boost/wiki/StartModMaint
I'd appreciate comments and corrections.
One of the questions that came up was how to number releases for individual libraries.
Say Boost.System wants to do a release before the next full Boost release ships. What do I call it? How do I document it? How do I tag it?
Strawman proposal ------------------------
* Call it "Boost.System 1.55.1 Point Release".
* Document it via the "readme" file that GitHub pesters you to add. Contents would give the title of the release and the release notes.
* Create a gh-pages branch with the same release notice.
* Tag it 1.55.1
Comments?
Hi, IMHO the Boost.System release shouldn't be correlated with Boost versions. E.g. Boost.Thread has version 4.2.0 and it appears on the documentation http://www.boost.org/doc/libs/1_55_0/doc/html/thread.html. For libraries that have not a version associated yet, they could start by the version they think it represents better the state of the library. Taking the history of the library should help to see on which version each library is (see http://www.boost.org/doc/libs/1_55_0/doc/html/thread/changes.html). I use to change the major version each time I introduce a breaking change, the minor version when I add more features and the patch when I just add fixes. With Git, I guess the author should create a release branch, each time he/she consider it is time to do a release. Of course this would mean that there is at least a version each time the library introduces changes on a official Boost release. This allows to take care of hot fixes independently of the other features the author is working on, which I think is something the Boost users are waiting for. Best, Vicente
On Dec 10, 2013, at 1:29 PM, "Vicente J. Botet Escriba" <vicente.botet@wanadoo.fr> wrote:
Le 10/12/13 17:41, Beman Dawes a écrit :
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
Thanks for your work on that, Beman.
One of the questions that came up was how to number releases for individual libraries.
Say Boost.System wants to do a release before the next full Boost release ships. What do I call it? How do I document it? How do I tag it?
Strawman proposal ------------------------
* Call it "Boost.System 1.55.1 Point Release".
-1
* Document it via the "readme" file that GitHub pesters you to add. Contents would give the title of the release and the release notes.
* Create a gh-pages branch with the same release notice.
* Tag it 1.55.1
IMHO the Boost.System release shouldn't be correlated with Boost versions. E.g. Boost.Thread has version 4.2.0 and it appears on the documentation http://www.boost.org/doc/libs/1_55_0/doc/html/thread.html.
+1
For libraries that have not a version associated yet, they could start by the version they think it represents better the state of the library. Taking the history of the library should help to see on which version each library is (see http://www.boost.org/doc/libs/1_55_0/doc/html/thread/changes.html). I use to change the major version each time I introduce a breaking change, the minor version when I add more features and the patch when I just add fixes.
Good
With Git, I guess the author should create a release branch, each time he/she consider it is time to do a release. Of course this would mean that there is at least a version each time the library introduces changes on a official Boost release. This allows to take care of hot fixes independently of the other features the author is working on, which I think is something the Boost users are waiting for.
Right ___ Rob (Sent from my portable computation engine)
On Tue, Dec 10, 2013 at 1:29 PM, Vicente J. Botet Escriba < vicente.botet@wanadoo.fr> wrote:
...
IMHO the Boost.System release shouldn't be correlated with Boost versions. E.g. Boost.Thread has version 4.2.0 and it appears on the documentation http://www.boost.org/doc/libs/1_55_0/doc/html/thread.html.
Good point. I agree.
For libraries that have not a version associated yet, they could start by the version they think it represents better the state of the library. Taking the history of the library should help to see on which version each library is (see http://www.boost.org/doc/libs/1_55_0/doc/html/thread/ changes.html). I use to change the major version each time I introduce a breaking change, the minor version when I add more features and the patch when I just add fixes.
I'll suggest something like that as a numbering strategy. ... OK, done. See https://svn.boost.org/trac/boost/wiki/StartModWorkflow
With Git, I guess the author should create a release branch, each time he/she consider it is time to do a release.
Whether or not a library maintainer uses a release branch is up to them, but every time master is changed (i.e. pushed to) Boost will be potentially treating it as a new release so it should have an updated release number. (The exact details of that will evolve over time.)
Of course this would mean that there is at least a version each time the library introduces changes on a official Boost release. This allows to take care of hot fixes independently of the other features the author is working on, which I think is something the Boost users are waiting for.
Yes, and easy point releases of my own libraries is certainly something I'm looking forward to. Thanks, --Beman
Beman Dawes wrote:
"* release.n.n.n for release staging branches. For example, release.1.56.2." Why the dot? Shouldn't it be release-1.56.2?
On Fri, Dec 13, 2013 at 3:52 PM, Peter Dimov <lists@pdimov.com> wrote:
Beman Dawes wrote:
See https://svn.boost.org/trac/boost/wiki/StartModWorkflow
"* release.n.n.n for release staging branches. For example, release.1.56.2."
Why the dot? Shouldn't it be release-1.56.2?
Also under "Release tag" describes names with spaces, e.g. "1.2.3 rc 2". Probably "1.2.3-rc2" would be less likely to cause any problems in various git clients. Michael
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/ mailman/listinfo.cgi/boost
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:
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.
You might want to recommend a setting for branch.autosetuprebase or provide a recommended .gitconfig in boostorg or on the web-site for all boost developers. I'd recommend branch.autosetuprebase=local (from the man page):
branch.autosetuprebase When a new branch is created with git branch or git checkout that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see "branch.<name>.rebase"). When never, rebase is never automatically set to true. When local, rebase is set to true for tracked branches of other local branches. When remote, rebase is set to true for tracked branches of remote-tracking branches. When always, rebase will be set to true for all tracking branches. See "branch.autosetupmerge" for details on how to set up a branch to track another branch. This option defaults to never.
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 rebase develop into the feature branch so that the eventual merge back to develop has less conflicts. Here is how the merge from develop to feature/add-checksum-option is done:
git checkout feature/add-checksum-option git merge develop
Otherwise the merge command above is wrong, since you always want to rebase onto a feature/bugfix/hotfix branch from the branch it was branched from. It should be:
git checkout feature/add-checksum-option git rebase develop The new commits from develop will be replayed on the common ancestor and the feature branch commits will be replayed on top of the new develop commits, as if the new commits done on develop had been done before instead of concurrently with the feature branch commits. Michael
LFrom https://svn.boost.org/trac/boost/wiki/StartModMaint: LLightweight library release<https://svn.boost.org/trac/boost/wiki/StartModMaint#Lightweightlibraryrelease> Small, simple libraries and simple releases just merge develop into master, tag master, and declare victory. git checkout master git merge --no-ff develop git tag -a 1.56.1 I'm not sure I understand why the merge for a lightweight library release should not be fast forwarded. If the feature branch commits onto develop have been done properly (i.e., cleaned up with an --interactive rebase or --squashed merged onto develop), it should be fine to fast forward them onto master. I thought what you described in "First post-svn conversion merge to master" was the one-time setup of the develop/master branch to allow fast forwarding of the develop branch onto the master. So why to lightweight and heavyweight merging have to be different in regards to fast forwarding? Michael
On Tue, Dec 17, 2013 at 1:03 AM, Cox, Michael <mhcox@bluezoosoftware.com>wrote:
LFrom https://svn.boost.org/trac/boost/wiki/StartModMaint: LLightweight library release<https://svn.boost.org/trac/boost/wiki/StartModMaint#Lightweightlibraryrelease>
Small, simple libraries and simple releases just merge develop into master, tag master, and declare victory.
git checkout master git merge --no-ff develop git tag -a 1.56.1
Also, has there been any thought to using signed tags? I know Linux uses them. I've never used them for my own little projects, but for something as important as boost, should they be used? Michael
On 17/12/2013 21:03, Quoth Cox, Michael:
LFrom https://svn.boost.org/trac/boost/wiki/StartModMaint: LLightweight library release<https://svn.boost.org/trac/boost/wiki/StartModMaint#Lightweightlibraryrelease>
Small, simple libraries and simple releases just merge develop into master, tag master, and declare victory.
git checkout master git merge --no-ff develop git tag -a 1.56.1
On an unrelated note: wasn't there agreement that libraries should not use the Boost version number for their own internal releases?
On Fri, Dec 13, 2013 at 5:52 PM, Peter Dimov <lists@pdimov.com> wrote:
Beman Dawes wrote:
See https://svn.boost.org/trac/boost/wiki/StartModWorkflow
"* release.n.n.n for release staging branches. For example, release.1.56.2."
Why the dot? Shouldn't it be release-1.56.2?
I copied it from somewhere. But you are right, http://nvie.com/posts/a-successful-git-branching-model/ uses "release-". Hum... That original blog post also uses "hotfix-" rather than "hotfix/" and doesn't use any prefix for feature branches. OTOH, git-flow tools defaults are different, at least on my Windows machine: D:\modular-boost>git flow init Which branch should be used for bringing forth production releases? - develop - master Branch name for production releases: [master] Which branch should be used for integration of the "next release"? - develop Branch name for "next release" development: [develop] How to name your supporting branch prefixes? Feature branches? [feature/] Release branches? [release/] Hotfix branches? [hotfix/] Support branches? [support/] Version tag prefix? [] So it looks like there has been some evolution in branch naming conventions. I'm inclined to go with the git-flow defaults. --Beman
2013/12/10 Beman Dawes <bdawes@acm.org>
Comments?
* Info about how to correctly delete old svn branches is required. Looks like a recommended solution will be to hide the branches instead of deleting/mering them. * Command for pulling and checkouting master/developer for *all* submodules looks like a good addition -- Best regards, Antony Polukhin
On Tue, Dec 10, 2013 at 2:38 PM, Henrik Sundberg <storangen@gmail.com>wrote:
On Tue, Dec 10, 2013 at 5:41 PM, Beman Dawes <bdawes@acm.org> wrote:
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
Comments?
Will the first Git release of Boost be 2.0? If not; why?
+ 1 Why don't you start a separate thread so your suggestion gets the airtime it deserves? --Beman
Em 10/12/2013, às 17:41, "Beman Dawes" <bdawes@acm.org> escreveu:
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
See https://svn.boost.org/trac/boost/wiki/StartModMaint
I'd appreciate comments and corrections.
Back in the SVN days, I waited for regression tests to cycle before merging into release from trunk. Now, how am I going to have this testing coverage? I can only test a couple of compilers locally, and I don't see how the regression testers can be configured to serve *all* lib developers at the same time, since x's author is locally testing her x/develop against (boost-x)/master --i.e. x and y have different world views. Thank you Joaquín M López Muñoz Telefónica Digital ________________________________ Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo. This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at: http://www.tid.es/ES/PAGINAS/disclaimer.aspx
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
See https://svn.boost.org/trac/boost/wiki/StartModMaint
I'd appreciate comments and corrections.
One of the questions that came up was how to number releases for individual libraries.
Say Boost.System wants to do a release before the next full Boost release ships. What do I call it? How do I document it? How do I tag it?
Strawman proposal ------------------------
* Call it "Boost.System 1.55.1 Point Release".
* Document it via the "readme" file that GitHub pesters you to add. Contents would give the title of the release and the release notes.
* Create a gh-pages branch with the same release notice.
* Tag it 1.55.1
Comments?
I still like having the name of the "product" (boost or name of the
On Tue, Dec 10, 2013 at 9:41 AM, Beman Dawes <bdawes@acm.org> wrote: library), e.g. boost-1.55.1 or accumulator-X.Y.Z.
From the web-site (comments in *italic blue*, additions in blue, deletions in green: PPrerequisites<https://svn.boost.org/trac/boost/wiki/StartModDev#Prerequisites>
- An understanding of Boost culture and the Developer's mailing list. Read more. <http://www.boost.org/community/> - An understanding of Boost Library Requirements and Guidelines<http://www.boost.org/development/requirements.html> . - The Git version control system. Read about Getting Started with Git.<https://svn.boost.org/trac/boost/wiki/Git/GitHome> If you are new to Git, install it and experiment a bit before coming back here. - A (free) GitHub <http://www.github.com/> account. Read about Getting Started with GitHub. <https://svn.boost.org/trac/boost/wiki/StartGitHub> - Your favorite supported compiler and development environment. *Where "supported compiler" is link to a page containing the list of supported compilers.* - A recent version of Boost installed. See Boost Getting Started<http://www.boost.org/more/getting_started/index.html>. (Either modular or pre-modular Boost will work.) - The b2 executable, created in the boost root directory during installation, added to your path. CCreating the simple library<https://svn.boost.org/trac/boost/wiki/StartModDev#Creatingthesimplelibrary> This procedure will create a trivial library named simple. Its public repository will be hosted in your own GitHub <http://github.com/> account. You will do development using a private repository that is located within a Boost installation on your local machine. This simulates your library being a sub-module of the Boost super-project <https://github.com/boostorg/boost> . - With your web browser, sign into your GitHub <https://github.com/> account and create a repository named simple. Select the option to automatically create a README file. Copy the URL of the newly created repository to your clipboard. - The remainder of the steps are run from the command line. - cd to the libs sub-directory of the Boost installation root directory, clone the newly created repository, and create the library's directory structure: git clone --recursive -o upstream -b develop git@github.com:boostorg/boost boost-root cd boost-root git submodule add -f -b develop git@github.com:<Github account>/simple libs/simple cd libs/simple mkdir -p include/boost/simple test doc example *I'd change "boost-root" -> "boost" (or leave it off in case of the "git clone").* ... - Using a text editor, create a file named twice.hpp in boost-root/libs/simple/include/boost/simple: #ifndef BOOST_SIMPLE_TWICE_HPP_INCLUDED_ #define BOOST_SIMPLE_TWICE_HPP_INCLUDED_#include <string> namespace boost { namespace simple { inline std::string twice(const std::string& s) { return s + s; } }}#endif // BOOST_SIMPLE_TWICE_HPP_INCLUDED_ CCommitting and pushing<https://svn.boost.org/trac/boost/wiki/StartModDev#Committingandpushing> OK, the basic structure and files of the library are present, so it is time to commit the changes to the local repo. Hint: git help command-name will display the documentation for command-name. *On Linux the command-name documentation displays directly to the console.* Michael --Beman
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
After reading the thread "avoiding fast-forward merges" and looking at the latest https://svn.boost.org/trac/boost/wiki/StartModMaint, I'm getting totally confused on the boost git flow. I thought all the commits on the develop branch of all the repositories are fast forwarded onto their master branches. Note, that the --no-ff still tries to fast forward the branch and adds a merge commit if the fast forward succeeded to "mark" the merge into master (not sure this is really necessary, since you should have a tag on that last fast forwarded commit The develop branch should *always* fast-forward, unless some history editing has occurred. Here's the description of the fast forward options from the man page of git-merge. --ff When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior. --no-ff Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag. --ff-only Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward. In fact, since we can't enforce fast forward merges on the server side on Github, The command line option should be --ff-only. That way if the merge fails, you know somehow a commit got on master that isn't on develop or maybe you have some stale branches you need to re-pull. With the --no-ff option and a master that isn't in sync with develop, you'll just put a merge commit on master and not fast forward the development history from the develop branch onto master. If you're lucky, you might get some merge conflicts that will alert you to the problem. On the StartModMaint page, there is command line sequence: cd modular-boost git checkout master git pull git submodule update Shouldn't that be "git checkout develop"? Are we not using the develop branch at all? Michael P.S. I tried to merge the develop branch onto the master branch in my superproject of my local repositories to simulate a release of boost. I got a ton of conflicts (looks like mostly submodule reference commits). Michael On Tue, Dec 10, 2013 at 9:41 AM, Beman Dawes <bdawes@acm.org> wrote:
I've been pecking away at "Getting Started with Modular Boost Library Maintenance".
See https://svn.boost.org/trac/boost/wiki/StartModMaint
I'd appreciate comments and corrections.
One of the questions that came up was how to number releases for individual libraries.
Say Boost.System wants to do a release before the next full Boost release ships. What do I call it? How do I document it? How do I tag it?
Strawman proposal ------------------------
* Call it "Boost.System 1.55.1 Point Release".
* Document it via the "readme" file that GitHub pesters you to add. Contents would give the title of the release and the release notes.
* Create a gh-pages branch with the same release notice.
* Tag it 1.55.1
Comments?
--Beman
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 12/25/2013 08:52 PM, Cox, Michael wrote:
After reading the thread "avoiding fast-forward merges" and looking at the latest https://svn.boost.org/trac/boost/wiki/StartModMaint, I'm getting totally confused on the boost git flow. I thought all the commits on the develop branch of all the repositories are fast forwarded onto their master branches. Note, that the --no-ff still tries to fast forward the branch and adds a merge commit
No it does not, where did you get that from?
if the fast forward succeeded to "mark" the merge into master (not sure this is really necessary, since you should have a tag on that last fast forwarded commit
I do not follow this, sorry.
The develop branch should *always* fast-forward, unless some history editing has occurred.
*always* fast-forward* - Why? The main idea of using --no-ff is to allow the develop branch to be the head of a sequence of commits where each commit represent a logical change to the system. Feature branches in git-flow allow long running feature work to go on in a separate branch with separate sequence of commits. When this work is ready to integrate into the develop branch, the feature branch developer(s) may leave the feature branch commits as is or clean it up before merge. The effect of a successful merge of feature/my-new-feature into develop with --no-ff will be *exactly* one new commit in develop regardless of the number of commits in the feature branch. The new commit will be titled "merge feature/my-new-feature" and the history of the work is in a separate fully merged branch. The local branch ref can be disposed of and is not needed any more. It does not need to be pushed to the public repository.
Here's the description of the fast forward options from the man page of git-merge.
--ff When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.
--no-ff Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.
--ff-only Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.
In fact, since we can't enforce fast forward merges on the server side on Github, The command line option should be --ff-only. That way if the merge fails, you know somehow a commit got on master that isn't on develop or maybe you have some stale branches you need to re-pull.
I am not saying this does not make sense, but I am sure there will be people having nits with the restrictions this policy imply as well. E.g. how do you handle hot fixes that are out of line with the commit sequence in develop.
With the --no-ff option and a master that isn't in sync with develop, you'll just put a merge commit on master and not fast forward the development history from the develop branch onto master.
Well as one that have used git-flow for some time at work, this is not at all my general feel of things. I am pretty sure you will end up with an identical tree in the master merge-commit as in the develop merged-from-commit in all but exceptional cases that I can think of may be caused by not following git flow-rules. I expect git-flow tools to automate checking for this. If you think of how change set actually flows in git-flow, there should not be anything in master that is not already in develop. Also, it is *not* like you will merge to master very often. You synchronize the work in develop if you use git-flow, not in master.
If you're lucky, you might get some merge conflicts that will alert you to the problem.
I like to see evidence of these sorts of problems in real use of git-flow and assess real git behavior and alternative fixes before I will conclude that this is an important issue by any measure. At least not important enough to not recomend git-flow as is. If you feel like documenting and supporting alternative git work-flows for boost library authors, I am sure it will be welcomed.
On the StartModMaint page, there is command line sequence:
cd modular-boost git checkout master git pull git submodule update
Shouldn't that be "git checkout develop"?
Maybe. I guess that depends if you want the latest boost release or the latest in master from each library.
Are we not using the develop branch at all?
For the boost supermodule I think it is where selection of and testing of submodule commit (release) candidates for next boost release will go on. I think each library may use develop as they please, but for larger libraries with a team of developers, use of develop is recommended as part of the git-flow process. Other work flows may be used as long as the master branch is reserved for releasable commits. -- Bjørn
On Wed, Dec 25, 2013 at 2:04 PM, Bjørn Roald <bjorn@4roald.org> wrote:
On 12/25/2013 08:52 PM, Cox, Michael wrote:
After reading the thread "avoiding fast-forward merges" and looking at the latest https://svn.boost.org/trac/boost/wiki/StartModMaint, I'm getting totally confused on the boost git flow. I thought all the commits on the develop branch of all the repositories are fast forwarded onto their master branches. Note, that the --no-ff still tries to fast forward the branch and adds a merge commit
No it does not, where did you get that from?
From the git-merge man page description of the --no-ff option (see below).
if the fast forward succeeded to "mark" the merge
into master (not sure this is really necessary, since you should have a tag on that last fast forwarded commit
I do not follow this, sorry.
The develop branch should *always*
fast-forward, unless some history editing has occurred.
*always* fast-forward* - Why?
Since all the commits that are on master are commits that were fast forwarded from develop on a previous merge and any future commits on develop will be successful merges from topic branches onto those same commits, everything should fast forward merge onto master. All conflicts/merge resolutions should occur on the topic branches via rebasing the develop branch onto the topic branch. Once the conflicts are resolved on the topic branch and the commits on it are split/squashed as desired (see git-rebase INTERACTIVE MODE section), the merge to develop should be clean and a --no-ff to ensure a merge commit is added to the develop branch. Merges from develop to master don't need the --no-ff because you only merge to master on an official release of Boost which should be tagged. Also if you make an annotated tag of the develop branch before merging into master, you will get the merge commit by default (see the last sentence of the --no-ff option description below). The main idea of using --no-ff is to allow the develop branch to be the
head of a sequence of commits where each commit represent a logical change to the system.
You don't need the --no-ff to have "the develop branch be the head of a sequence of commits where each commit represents a logical change to the system". The interactive rebasing of the topic branch should give you that. Most topic branches can be restructured into a couple of commits, e.g. one commit for library code changes and one commit for modified/new tests or if you really don't care how you got to the end result, you can use a --squash commit to compress it into one commit.
Feature branches in git-flow allow long running feature work to go on in a separate branch with separate sequence of commits. When this work is ready to integrate into the develop branch, the feature branch developer(s) may leave the feature branch commits as is or clean it up before merge. The effect of a successful merge of feature/my-new-feature into develop with --no-ff will be *exactly* one new commit in develop regardless of the number of commits in the feature branch.
I think your confusing the merge option --no-ff with the --squash option.
The new commit will be titled "merge feature/my-new-feature" and the history of the work is in a separate fully merged branch. The local branch ref can be disposed of and is not needed any more. It does not need to be pushed to the public repository.
Agreed.
Here's the description of the
fast forward options from the man page of git-merge.
--ff When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.
--no-ff Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.
--ff-only Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.
In fact, since we can't enforce fast forward merges on the server side on Github, The command line option should be --ff-only. That way if the merge fails, you know somehow a commit got on master that isn't on develop or maybe you have some stale branches you need to re-pull.
I am not saying this does not make sense, but I am sure there will be people having nits with the restrictions this policy imply as well. E.g. how do you handle hot fixes that are out of line with the commit sequence in develop.
I'm not sure I follow the part about the nits. As far as hot fixes go (or any type of topic branch for that matter), the same process is followed: 1. The developer continually rebases other peoples changes onto the topic branch while working on the changes to implement the hotfix, feature, etc. 2. The topic branch cleanly builds and passes all tests. 3. Optionally the developer interactively rebases to structure the commits to a small number of logical commits, or if that's not important, --squash merges it into develop
With the --no-ff
option and a master that isn't in sync with develop, you'll just put a merge commit on master and not fast forward the development history from the develop branch onto master.
Well as one that have used git-flow for some time at work, this is not at all my general feel of things. I am pretty sure you will end up with an identical tree in the master merge-commit as in the develop merged-from-commit in all but exceptional cases that I can think of may be caused by not following git flow-rules. I expect git-flow tools to automate checking for this. If you think of how change set actually flows in git-flow, there should not be anything in master that is not already in develop. Also, it is *not* like you will merge to master very often. You synchronize the work in develop if you use git-flow, not in master.
Exactly! But if you run "git branch --contains master" in all the repository, it will tell you that the HEAD commit of master is not in develop (since it only prints out master). And the way SHA1s work (i.e. the entire history of that HEAD commit is encoded in it's SHA1), that means git thinks *none*of the commits in master are in develop. Note, even if you can find a commit that has the exact same comment with the exact same changes in both master and develop, but the SHA1 is different, then git considers that a different commit.
If you're lucky, you might get some merge
conflicts that will alert you to the problem.
I like to see evidence of these sorts of problems in real use of git-flow and assess real git behavior and alternative fixes before I will conclude that this is an important issue by any measure. At least not important enough to not recomend git-flow as is.
If you feel like documenting and supporting alternative git work-flows for boost library authors, I am sure it will be welcomed.
I am advocating git-flow workflow. I'm just telling you the git commands your using don't look like they properly implement it. The changes should *fast forward* flow from topic branches to develop to master.
On the StartModMaint page, there is command line sequence:
cd modular-boost git checkout master git pull git submodule update
Shouldn't that be "git checkout develop"?
Maybe. I guess that depends if you want the latest boost release or the latest in master from each library.
Are we not using the develop
branch at all?
For the boost supermodule I think it is where selection of and testing of submodule commit (release) candidates for next boost release will go on.
I think each library may use develop as they please, but for larger libraries with a team of developers, use of develop is recommended as part of the git-flow process. Other work flows may be used as long as the master branch is reserved for releasable commits.
From the Modular Boost Library Workflow Overview<https://svn.boost.org/trac/boost/wiki/StartModWorkflow>,
the use of the develop branch doesn't sound optional. Also from Peter's proposal <http://thread.gmane.org/gmane.comp.lib.boost.devel/247192> it doesn't sound optional. Michael P.S. I think that the problem that git doesn't think all the commits in develop are not in master may be because the way the conversion from svn was done (or at least the way I understand it was done). My understanding is that the revisions on develop were created from the trunk and the revisions on master were created from the {tags,branches}/release/* revisions. If that's the case, I'm not sure you can ever get git to think all of the master commits are in develop. The master branches have to be linearized versions of all the svn revisions from trunk, {tags,branches}/release/* in (probably) revision number sequence and then just create develop from a "git checkout -b develop master". This way master an develop are identical.
On 12/26/2013 01:03 PM, Cox, Michael wrote:
On Wed, Dec 25, 2013 at 2:04 PM, Bjørn Roald <bjorn@4roald.org> wrote:
On 12/25/2013 08:52 PM, Cox, Michael wrote:
After reading the thread "avoiding fast-forward merges" and looking at the latest https://svn.boost.org/trac/boost/wiki/StartModMaint, I'm getting totally confused on the boost git flow. I thought all the commits on the develop branch of all the repositories are fast forwarded onto their master branches. Note, that the --no-ff still tries to fast forward the branch and adds a merge commit
No it does not, where did you get that from?
From the git-merge man page description of the --no-ff option (see below).
I think that man page description can be improved, it is not very clear in the point that --no-ff means no fast-forward, but that is what it means. It attempts to say that if the merge is a simple fast forward, It will instead make exactly one new commit. Note that a fast forward involves no new commit, instead it just moves the ref to the branch head forward along the path of the branch you are merging into your checked out branch. I recommend to test it.
if the fast forward succeeded to "mark" the merge
into master (not sure this is really necessary, since you should have a tag on that last fast forwarded commit
I do not follow this, sorry.
The develop branch should *always*
fast-forward, unless some history editing has occurred.
*always* fast-forward* - Why?
Since all the commits that are on master are commits that were fast forwarded from develop on a previous merge and any future commits on develop will be successful merges from topic branches onto those same commits, everything should fast forward merge onto master. All conflicts/merge resolutions should occur on the topic branches via rebasing the develop branch onto the topic branch. Once the conflicts are resolved on the topic branch and the commits on it are split/squashed as desired (see git-rebase INTERACTIVE MODE section), the merge to develop should be clean and a --no-ff to ensure a merge commit is added to the develop branch. Merges from develop to master don't need the --no-ff because you only merge to master on an official release of Boost which should be tagged. Also if you make an annotated tag of the develop branch before merging into master, you will get the merge commit by default (see the last sentence of the --no-ff option description below).
The main idea of using --no-ff is to allow the develop branch to be the
head of a sequence of commits where each commit represent a logical change to the system.
You don't need the --no-ff to have "the develop branch be the head of a sequence of commits where each commit represents a logical change to the system". The interactive rebasing of the topic branch should give you that. Most topic branches can be restructured into a couple of commits, e.g. one commit for library code changes and one commit for modified/new tests or if you really don't care how you got to the end result, you can use a --squash commit to compress it into one commit.
I do not generate any internal heat on eighter way, I just recomend following what the git-flow actually say as that is well known and documented.
Feature branches in git-flow allow long running feature work to go on in a separate branch with separate sequence of commits. When this work is ready to integrate into the develop branch, the feature branch developer(s) may leave the feature branch commits as is or clean it up before merge. The effect of a successful merge of feature/my-new-feature into develop with --no-ff will be *exactly* one new commit in develop regardless of the number of commits in the feature branch.
I think your confusing the merge option --no-ff with the --squash option.
No I am not.
The new commit will be titled "merge feature/my-new-feature" and the history of the work is in a separate fully merged branch. The local branch ref can be disposed of and is not needed any more. It does not need to be pushed to the public repository.
Agreed.
Here's the description of the
fast forward options from the man page of git-merge.
--ff When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default behavior.
--no-ff Create a merge commit even when the merge resolves as a fast-forward. This is the default behaviour when merging an annotated (and possibly signed) tag.
--ff-only Refuse to merge and exit with a non-zero status unless the current HEAD is already up-to-date or the merge can be resolved as a fast-forward.
In fact, since we can't enforce fast forward merges on the server side on Github, The command line option should be --ff-only. That way if the merge fails, you know somehow a commit got on master that isn't on develop or maybe you have some stale branches you need to re-pull.
I am not saying this does not make sense, but I am sure there will be people having nits with the restrictions this policy imply as well. E.g. how do you handle hot fixes that are out of line with the commit sequence in develop.
I'm not sure I follow the part about the nits. As far as hot fixes go (or any type of topic branch for that matter), the same process is followed:
1. The developer continually rebases other peoples changes onto the topic branch while working on the changes to implement the hotfix, feature, etc. 2. The topic branch cleanly builds and passes all tests. 3. Optionally the developer interactively rebases to structure the commits to a small number of logical commits, or if that's not important, --squash merges it into develop
I am short on time and cant reply as I would want to, I think we should simply recommend something that are well understood, Unless someone steps up and are willing to support other recommended ways of using git. I am probably going to be largely off-line the next 2 weeks, will try to check in from time to time. I may reply to the rest later when I have read it. Best regards -- Bjørn
On 26 December 2013 12:03, Cox, Michael <mhcox@bluezoosoftware.com> wrote:
I'm not sure I follow the part about the nits. As far as hot fixes go (or any type of topic branch for that matter), the same process is followed:
1. The developer continually rebases other peoples changes onto the topic branch while working on the changes to implement the hotfix, feature, etc. 2. The topic branch cleanly builds and passes all tests. 3. Optionally the developer interactively rebases to structure the commits to a small number of logical commits, or if that's not important, --squash merges it into develop
We have a lot of git novices here, getting them to continually rebase branches is probably a bad idea.
On Thu, Dec 26, 2013 at 7:41 AM, Daniel James <daniel@calamity.org.uk>wrote:
On 26 December 2013 12:03, Cox, Michael <mhcox@bluezoosoftware.com> wrote:
I'm not sure I follow the part about the nits. As far as hot fixes go (or any type of topic branch for that matter), the same process is followed:
1. The developer continually rebases other peoples changes onto the topic branch while working on the changes to implement the hotfix, feature, etc. 2. The topic branch cleanly builds and passes all tests. 3. Optionally the developer interactively rebases to structure the commits to a small number of logical commits, or if that's not important, --squash merges it into develop
We have a lot of git novices here, getting them to continually rebase branches is probably a bad idea.
That's why I've suggested here<http://article.gmane.org/gmane.comp.lib.boost.devel/247348> boost should consider using bitbucket.org with its branch restrictions features<http://blog.bitbucket.org/2013/09/16/take-control-with-branch-restrictions> to avoid accidentally rewriting history, if github won't provide that same functionality (supposedly Github Enterprise has that functionality). But I'm not suggesting moving to a rebase workflow policy vs. the git-flow merge workflow policy. Even in a merge workflow policy, there are times when rebasing is better. See this interesting Atlassian blog entry<http://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/> (the creators of bitbucket.org) describing the unresolved debate about whether a rebase or merge workflow policy is better and when rebasing is even appropriate in a merge workflow policy. Michael
On Wed, Dec 25, 2013 at 2:52 PM, Cox, Michael <mhcox@bluezoosoftware.com>wrote: ...
On the StartModMaint page, there is command line sequence:
cd modular-boost git checkout master git pull git submodule update
Shouldn't that be "git checkout develop"?
No. Read the explanation about testing a submodule's development branch against super project master and master (as of the super-project) for all other libraries.
Are we not using the develop branch at all?
The library being worked on is encouraged to use a development branch such as "develop". The commands to do the checkout appear a bit after the sequence you quoted above. cd modular-boost/libs/mylib git checkout develop
P.S. I tried to merge the develop branch onto the master branch in my superproject of my local repositories to simulate a release of boost. I got a ton of conflicts (looks like mostly submodule reference commits).
AFAIK, the release managers (who are presumably the only folks who would ever do super-project merges) are just cherry-picking for now. I'm not sure how Daniel's script to update the submodules works. --Beman
On 26 December 2013 00:28, Beman Dawes <bdawes@acm.org> wrote:
On Wed, Dec 25, 2013 at 2:52 PM, Cox, Michael <mhcox@bluezoosoftware.com>wrote:
P.S. I tried to merge the develop branch onto the master branch in my superproject of my local repositories to simulate a release of boost. I got a ton of conflicts (looks like mostly submodule reference commits).
AFAIK, the release managers (who are presumably the only folks who would ever do super-project merges) are just cherry-picking for now. I'm not sure how Daniel's script to update the submodules works.
It just updates submodules to the latest version. Merging will never really work on the super project as they're updated independently. The only thing that the current develop branch is good for is making up for the shortcomings in our testing setup. This is one of the reasons why Peter Dimov suggested changing the branches in his proposal, and I suggested that much of what's in the super project should be moved into submodules.
On Thu, Dec 26, 2013 at 2:24 AM, Daniel James <daniel@calamity.org.uk>wrote:
On 26 December 2013 00:28, Beman Dawes <bdawes@acm.org> wrote:
On Wed, Dec 25, 2013 at 2:52 PM, Cox, Michael <mhcox@bluezoosoftware.com wrote:
P.S. I tried to merge the develop branch onto the master branch in my superproject of my local repositories to simulate a release of boost. I got a ton of conflicts (looks like mostly submodule reference commits).
AFAIK, the release managers (who are presumably the only folks who would ever do super-project merges) are just cherry-picking for now. I'm not sure how Daniel's script to update the submodules works.
It just updates submodules to the latest version.
On what branch in the superproject to what branch in the submodules? develop -> master I hope?
Merging will never really work on the super project as they're updated independently. The
Why is the superproject's master branch being updated? That should occur only when the release managers are ready to release boost by merging the superproject's develop branch into master.
only thing that the current develop branch is good for is making up for the shortcomings in our testing setup. This is one of the reasons why Peter Dimov suggested changing the branches in his proposal, and I
This proposal <http://thread.gmane.org/gmane.comp.lib.boost.devel/247192> or has it changed? Michael
suggested that much of what's in the super project should be moved into submodules.
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 26 December 2013 12:41, Cox, Michael <mhcox@bluezoosoftware.com> wrote:
On Thu, Dec 26, 2013 at 2:24 AM, Daniel James <daniel@calamity.org.uk>wrote:
It just updates submodules to the latest version.
On what branch in the superproject to what branch in the submodules? develop -> master I hope?
No, until a decision is made otherwise, I'm just following what the conversion established.
Merging will never really work on the super project as they're updated independently. The
Why is the superproject's master branch being updated? That should occur only when the release managers are ready to release boost by merging the superproject's develop branch into master.
We haven't settled on how the superproject will be released, it might not work that way. One possible alternative is creating a release branch from master. For now, master acts as release did in subversion.
only thing that the current develop branch is good for is making up for the shortcomings in our testing setup. This is one of the reasons why Peter Dimov suggested changing the branches in his proposal, and I
This proposal <http://thread.gmane.org/gmane.comp.lib.boost.devel/247192> or has it changed?
No, it hasn't.
participants (11)
-
Antony Polukhin -
Beman Dawes -
Bjørn Roald -
Cox, Michael -
Daniel James -
Gavin Lambert -
Henrik Sundberg -
JOAQUIN M. LOPEZ MUÑOZ -
Peter Dimov -
Rob Stewart -
Vicente J. Botet Escriba