Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-10558

Jenkins mercurial plugin - add support for bookmarks

    • Icon: New Feature New Feature
    • Resolution: Unresolved
    • Icon: Critical Critical
    • mercurial-plugin
    • None
    • all

      Mercurial plugin supports branches, which is nice. However, there are a lot of people, especially these coming from git, who think that such named branches are no good (they stay for ever, the branch is baked into the commit), and prefer using bookmarks* instead. There seems to be a lot of momentum around that extension, which culminated in it being incorporated into mercurial core since hg 1.8 (which means it is not an extension any more; rather, it is a first-class citizen now).

      Bookmarks is the closest thing that mercurial currently supports that resembles git-like branches. This is what we would love to use (as we share the view that such long running named branches are no good), but we can't since the Jenkins plugin doesn't support this (we would like to create ad-hoc Jenkins jobs for our features (topic branches), which are bookmarks, not branches, and once the feature is implemented, we drop the Jenkins job).

      A basic bookmarks workflow (in a repository):
      $ hg bookmark feature_x
      ... work work work
      $ hg commit -m 'some feature_x code'
      ... push to some canonical repo for others to see
      $ hg push -B feature_x -f // -f most likely needed as bookmarks are simply 'named heads' - but it doesn't matter for Jenkins

      Now some other collaborator:
      $ hg incoming -B // shows that there is a new bookmark, 'feature_x'
      $ hg pull -B feature_x
      and they can now start working on this bookmark ('lightweight branch').

      I tried simply changing the value of the 'branch' field in my project configuration, but it doesn't work. But it is very close. What seems not to work is the fact that Jenkins doesn't know the '-B' switch, and doesn't know that I want to import the bookmark. What Jenkins does is this (shortened a little, the template is not used):
      $ hg incoming --quiet --bundle hg.bundle --template "..." --rev feature_x
      $ hg unbundle hg.bundle
      adding changesets
      adding manifests
      adding file changes
      added 1 changesets with 1 changes to 1 files (+1 heads)
      (run 'hg heads' to see heads, 'hg merge' to merge)
      $ hg update --clean --rev feature_x
      abort: unknown revision 'test'!

      This means that the incoming changes were found with the bookmark name and were pulled, but the bookmark itself wasn't imported, and doesn't exist locally - and update fails. With the '-B' switch, it would work fine (tested on the command line):

      $ hg incoming --quiet --bundle hg.bundle --template "..." --rev feature_x
      $ hg unbundle hg.bundle
      adding changesets
      adding manifests
      adding file changes
      added 1 changesets with 1 changes to 1 files (+1 heads)
      (run 'hg heads' to see heads, 'hg merge' to merge)
      $ hg pull B feature_x // <---------------------------- that's the missing link
      no changes found
      importing bookmark test
      $ hg update --clean --rev feature_x
      1 files updated, 0 files merged, 0 files removed, 0 files unresolved

      With the single call to pull the bookmark (which effectively imports it) makes it work!

      Of course, there could be a mix of branch and bookmark, so the 'incoming' should use the branch name, and if and only if a bookmark is specified, a 'pull -B <bookmark_name>' should be issued, and the update should use the bookmark and not the branch. This means there should be some additional field for the bookmark, and some additional logic, but not that much, I think?

      I will take a look at the source code on GitHub to see if maybe I could help you with that, if you are interested?

      I as setting it as critical, as it has the potential to influence the decision whether we can use Jenkins or not for this project. Naturally, you are the bosses so feel free to squash it.

      As a side note: what is the relationship between the Jenkins Mercurial Plugin (version 1.37, code on GitHub) and Hudson Mercurial Plugin (version 1.35, couldn't find a repository)? I am asking since we use both, and it would be nice if the code could be written once and work for both servers, of course ;d

      Regards,
      wujek

          [JENKINS-10558] Jenkins mercurial plugin - add support for bookmarks

          tags and bookmarks are two different things.
          Therefore, it doesn't supersede the other issue which is not really connected except the fact it affects mercurial plugin.

          Most of the time, you will use Tags for tagging a public or some important release. In many situation, you will associate a branch as well so that you can bug fix this revision. In that respect, I'm not sure it is so important to pull from tag (though it doesn't hurt if it can).
          On the other hand, Bookmarks and their new first class citizen status are quite important to support on a CI standpoint as they really represent branches of some development (light branch but still branches).

          Any chance that the patch provided by wujek is being incorporated?

          Frederic Latour added a comment - tags and bookmarks are two different things. Therefore, it doesn't supersede the other issue which is not really connected except the fact it affects mercurial plugin. Most of the time, you will use Tags for tagging a public or some important release. In many situation, you will associate a branch as well so that you can bug fix this revision. In that respect, I'm not sure it is so important to pull from tag (though it doesn't hurt if it can). On the other hand, Bookmarks and their new first class citizen status are quite important to support on a CI standpoint as they really represent branches of some development (light branch but still branches). Any chance that the patch provided by wujek is being incorporated?

          Looking for this myself — the Git plugin supports branches (watching/building multiple branches); it seems like using an identical model for the Mercurial plugin with bookmarks would solve this nicely.

          Michael Ekstrand added a comment - Looking for this myself — the Git plugin supports branches (watching/building multiple branches); it seems like using an identical model for the Mercurial plugin with bookmarks would solve this nicely.

          Jesse Glick added a comment -

          http://mercurial.selenic.com/wiki/Bookmarks is the current feature description.

          Since it makes no sense to specify both a branch name and a bookmark, probably the UI should be a checkbox that indicates that the "branch" field is really a bookmark name. (It would be great if the plugin could automatically detect this, but I doubt that is possible.)

          Pull requests implementing this feature without affecting existing usage would be considered. (Wujek's change may make subtle changes to behavior of jobs not using bookmarks; the use of --rev rather than --branch is intentional. It also includes no new tests, is long out of date with master, and does not seem to be available as a pull request anyway.)

          Jesse Glick added a comment - http://mercurial.selenic.com/wiki/Bookmarks is the current feature description. Since it makes no sense to specify both a branch name and a bookmark, probably the UI should be a checkbox that indicates that the "branch" field is really a bookmark name. (It would be great if the plugin could automatically detect this, but I doubt that is possible.) Pull requests implementing this feature without affecting existing usage would be considered. (Wujek's change may make subtle changes to behavior of jobs not using bookmarks; the use of --rev rather than --branch is intentional. It also includes no new tests, is long out of date with master , and does not seem to be available as a pull request anyway.)

          Mike Wilson added a comment -

          This sounds interesting, but I wonder about bookmarks vs branches. You mention that some users prefer bookmarks as branches stay around forever. Do you see the problem with persistent branch names as something causing performance problems (too many branch names building up over time) or more of supporting some users' personal preferences of how to use Mercurial?

          Mike Wilson added a comment - This sounds interesting, but I wonder about bookmarks vs branches. You mention that some users prefer bookmarks as branches stay around forever. Do you see the problem with persistent branch names as something causing performance problems (too many branch names building up over time) or more of supporting some users' personal preferences of how to use Mercurial?

          Mostly a user-experience issue. Branches, due their longevity, leave a persistent record in the changelog that can be confusing to read. Named branches are typically used for long-standing branches (e.g. a "stable" branch), with bookmarks being preferred for things like feature branches. The Mercurial UI is moving in this direction - recent Mercurial versions print a warning and ask for confirmation when creating new named branches.

          Michael Ekstrand added a comment - Mostly a user-experience issue. Branches, due their longevity, leave a persistent record in the changelog that can be confusing to read. Named branches are typically used for long-standing branches (e.g. a "stable" branch), with bookmarks being preferred for things like feature branches. The Mercurial UI is moving in this direction - recent Mercurial versions print a warning and ask for confirmation when creating new named branches.

          Mike Wilson added a comment -

          Great, thanks. I can clearly see uses both for branches that keep their names forever (for documentation reasons), and for ones that drop their names once finished.

          I guess bookmarks could be used for both (just don't delete the names you want to keep?) but named branches are probably better for the former as they also have the active/closed status to aid you in finding relevant branches?

          So this would boil down to that support for auto-building both all branches and all bookmarks would be valuable
          [now voting for both this ticket and JENKINS-11102]

          Mike Wilson added a comment - Great, thanks. I can clearly see uses both for branches that keep their names forever (for documentation reasons), and for ones that drop their names once finished. I guess bookmarks could be used for both (just don't delete the names you want to keep?) but named branches are probably better for the former as they also have the active/closed status to aid you in finding relevant branches? So this would boil down to that support for auto-building both all branches and all bookmarks would be valuable [now voting for both this ticket and JENKINS-11102]

          This is supported as long as you enable the bookmarks extension in .hgrc This ticket can probably be marked as complete/done.

          Roy Sindre Norangshol added a comment - This is supported as long as you enable the bookmarks extension in .hgrc This ticket can probably be marked as complete/done.

          Jesse Glick added a comment -

          @rockj: even if so, need to at least confirm this in an automated test, and document that properly. Anyway users cannot be expected to manually update .hgrc slave nodes; the plugin should manage this.

          Jesse Glick added a comment - @rockj: even if so, need to at least confirm this in an automated test, and document that properly. Anyway users cannot be expected to manually update .hgrc slave nodes; the plugin should manage this.

          Igor Kostenko added a comment -

          When you are using repository caching bookmarks are lost because bundle doesn't support them

          Igor Kostenko added a comment - When you are using repository caching bookmarks are lost because bundle doesn't support them

          Jesse Glick added a comment -

          Need to add MercurialSCM.RevisionType.BOOKMARK and then review & test all operations (clone, update, poll, changelog) to make sure they work smoothly with bookmarks instead of branches, enabling the bookmark plugin if this is not already the default in Mercurial; and, as @igorkostenko noted, determine whether bookmarks are supportable with caching, and if not at least prevent the user from configuring a job with both bookmarks and caching.

          Jesse Glick added a comment - Need to add MercurialSCM.RevisionType.BOOKMARK and then review & test all operations (clone, update, poll, changelog) to make sure they work smoothly with bookmarks instead of branches, enabling the bookmark plugin if this is not already the default in Mercurial; and, as @igorkostenko noted, determine whether bookmarks are supportable with caching, and if not at least prevent the user from configuring a job with both bookmarks and caching.

            jglick Jesse Glick
            wujek_srujek wujek srujek
            Votes:
            8 Vote for this issue
            Watchers:
            9 Start watching this issue

              Created:
              Updated: