Update branching option to branch from another branch.

Previously if updating a branch in the ARMmbed version of an example
repo, the branch would be created initially from master. This update
allows the new branch to be created by any pre-existing branch.
This update also moves the branch / fork / tag configuration data to the
json config file. It thus simplifies the command line.
-b on its own now indicates use the branch information in the config
-f on its own now indicates use the fork information in the config

Author: adbridge

tools/test/examples/examples.json

@@ -1,4 +1,17 @@
-{
+{ 
+  "update-config" : {
+      "help" : "Update each example repo with a version of mbed-os identified by the tag",
+      "via-fork" : {
+        "help" : "-f cmd line option. Update a fork",
+        "github-user" : "adbridge"          
+      },
+      "via-branch" : {
+        "help" : "-b cmd line option. Update dst branch, created from src branch",
+        "src-branch" : "mbed-os-5.5.0-rc1-oob",
+        "dst-branch" : "mbed-os-5.5.0-rc2-oob"    
+      },
+      "tag" : "mbed-os-5.5.0-rc2"
+  },
   "examples": [
     {
       "name": "mbed-os-example-blinky",

tools/test/examples/update.py

@@ -232,106 +232,101 @@ def prepare_fork(arm_example):
             return False
     return True
 
-def prepare_branch(branch):
+def prepare_branch(src, dst):
     """ Set up at branch ready for use in updating examples 
         
     Description:
     
-    This function checks whether or not the supplied branch exists.
-    If it does not, the branch is created and pushed to the origin.
+    This function checks whether or not the supplied dst branch exists.
+    If it does not, the branch is created from the src and pushed to the origin.
     The branch is then switched to.
     
     Args:
-    arm_example - Full GitHub repo path for original example 
+    src - branch to create the dst branch from
+    dst - branch to update
+
+    Return:
     ret - True if the fork was synchronised successfully, False otherwise
     
     """
 
-    update_log.debug("Preparing branch: %s", branch)
+    update_log.debug("Preparing branch: %s", dst)
 
     # Check if branch already exists or not.
     cmd = ['git', 'branch']
     return_code, output = run_cmd_with_output(cmd)
 
-    if not branch in output:
+    if not dst in output:
+        
         # OOB branch does not exist thus create it and then check it out
-        cmd = ['git', 'checkout', '-b', branch]
+
+        # First ensure we are on the src branch
+        cmd = ['git', 'checkout', src]
         return_code = run_cmd(cmd)
         if not return_code:
-
-            # Push new branch upstream
-            cmd = ['git', 'push', '-u', 'origin', branch]
+                
+            cmd = ['git', 'checkout', '-b', dst]
             return_code = run_cmd(cmd)
+            if not return_code:
+
+                # Push new branch upstream
+                cmd = ['git', 'push', '-u', 'origin', dst]
+                return_code = run_cmd(cmd)
     else: 
-        cmd = ['git', 'checkout', branch]
+        cmd = ['git', 'checkout', dst]
         return_code = run_cmd(cmd)
 
     if return_code:
-        update_log.error("Failed to prepare branch: %s", branch)
+        update_log.error("Failed to prepare branch: %s", dst)
         return False
 
     return True
 
-def upgrade_example(github, example, tag, ref,
-                    user='ARMmbed', branch='master'):
+def upgrade_example(github, example, tag, ref, user, src, dst):
     """ Upgrade all versions of mbed-os.lib found in the specified example repo
     
     Description:
     
     Clone a version of the example specified and upgrade all versions of 
     mbed-os.lib found within its tree.  The version cloned and how it 
-    is upgraded depends on the user and branch specified. Only two options 
-    are valid:
-    1) ARMmbed + non master branch
-       This option will update the branch directly in the ARMmbed repo. If the 
-       branch does not exist it will be first created.
-
-    2) alternative user + master branch
-                
-       This option assumes that a fork of the repo exists in the specified user's
-       account. The fork will first be updated so that it is up to date with the 
-       upstream  version , then the fork will be updated and a PR raised against 
-       the upstream ie ARMmbed repo.
-        
+    is upgraded depends on the user, src and dst settings.
+    1) user == None 
+       The destination branch will be updated with the version of mbed-os 
+       idenfied by the tag. If the destination branch does not exist then it
+       will be created from the source branch.
+
+    2) user != None 
+       The master branch of a fork of the example will be updated with the 
+       version of mbed-os identified by the tag.
+            
     Args:
     github - GitHub instance to allow internal git commands to be run
     example - json example object containing the GitHub repo to update.
     tag - GitHub tag corresponding to a version of mbed-os to upgrade to.
     ref - SHA corresponding to the tag
-    user - GitHub user name (defaults to 'ARMmbed' if not supplied)
-    branch - branch to update (defaults to 'master' if not supplied)
+    user - GitHub user name 
+    src - branch to create the dst branch from
+    dst - branch to update
     
     returns True if the upgrade was successful, False otherwise
     """
+    
+    # If a user has not been specified then branch update will be used and thus
+    # the git user will be ARMmbed.        
+    if not user:
+        user = 'ARMmbed'
 
     ret = False
     update_log.info("Updating example '%s'", example['name'])
     update_log.debug("User: %s", user)
-    update_log.debug("Branch: %s", branch)
-
-    # First check validity of user/branch combination
-    if ((user == 'ARMmbed' and branch == 'master') or 
-        (user != 'ARMmbed' and branch != 'master')):
-        update_log.error("Invalid user/branch combination")
-        return False
+    update_log.debug("Src branch: %s", (src or "None"))
+    update_log.debug("Dst branch: %s", (dst or "None"))
 
     cwd = os.getcwd()
 
-    upstream_repo = 'ARMmbed/'+ example['name']
     update_repo = "https://github.com/" + user + '/' + example['name'] 
-
-    update_log.debug("Upstream repository: %s", upstream_repo)
     update_log.debug("Update repository: %s", update_repo)
 
-    # Check access to mbed-os repo
-    try:
-        repo = github.get_repo(upstream_repo, False)
-
-    except:
-        update_log.error("Upstream repo: %s, does not exist - skipping", upstream_repo)
-        return False
-
-
     # Clone the example repo
     clone_cmd = ['git', 'clone', update_repo]
     return_code = run_cmd(clone_cmd)
@@ -343,13 +338,11 @@ def upgrade_example(github, example, tag, ref,
 
         os.chdir(example['name'])
 
-        # If the user is not the default, then a fork will be used. Thus
-        # synchronise the user fork with the upstream 
-        if user != 'ARMmbed':
+        # If the user is ARMmbed then a branch is used.
+        if user == 'ARMmbed':
+            prepare_branch(src, dst)    
+        else:          
             prepare_fork(example['github'])
-
-        if branch != 'master':
-            prepare_branch(branch)    
 
         for example_directory in example_directories:
             if not upgrade_single_example(example, tag, os.path.relpath(example_directory, example['name']), ref):
@@ -369,8 +362,22 @@ def upgrade_example(github, example, tag, ref,
             return_code = run_cmd(push_cmd)
 
             if not return_code:
-                if user != 'ARMmbed':                                
-                    body = "Please test/merge this PR and then tag Master with " + tag
+                # If the user is not ARMmbed then a fork is being used
+                if user != 'ARMmbed': 
+                    
+                    upstream_repo = 'ARMmbed/'+ example['name']
+                    update_log.debug("Upstream repository: %s", upstream_repo)
+                    # Check access to mbed-os repo
+                    try:
+                        repo = github.get_repo(upstream_repo, False)
+
+                    except:
+                        update_log.error("Upstream repo: %s, does not exist - skipping", upstream_repo)
+                        return False
+           
+                    body = "Please test this PR.\n"
+                    body += "If successful then merge, otherwise provide a known issue.\n"
+                    body += "Once you get notification of the release being made public then tag Master with " + tag
                     # Raise a PR from release-candidate to master
                     user_fork = user + ':master' 
                     try:
@@ -409,16 +416,15 @@ def create_work_directory(path):
 
     parser = argparse.ArgumentParser(description=__doc__,
                                      formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument('tag', help="mbed-os tag to which all examples will be updated")
     parser.add_argument('-c', '--config_file', help="Path to the configuration file (default is 'examples.json')", default='examples.json')
     parser.add_argument('-T', '--github_token', help="GitHub token for secure access")
     parser.add_argument('-l', '--log-level', 
                         help="Level for providing logging output", 
                         default='INFO')
 
     exclusive = parser.add_mutually_exclusive_group(required=True)
-    exclusive.add_argument('-U', '--github_user', help="GitHub user for forked repos, mutually exclusive to branch option")
-    exclusive.add_argument('-b', '--branch', help="Branch to be updated, mutually exclusive to user option")
+    exclusive.add_argument('-f', '--fork', help="Update a fork", action='store_true')
+    exclusive.add_argument('-b', '--branch', help="Update a branch", action='store_true')
 
     args = parser.parse_args()
 
@@ -441,9 +447,24 @@ def create_work_directory(path):
     create_work_directory('examples')
 
     github = Github(args.github_token)
+    config = json_data['update-config']
+    tag = config['tag']
+
+    user = None
+    src = "master"
+    dst = None
+
+    if args.fork:
+        user = config['via-fork']['github-user']
+    elif args.branch:
+        src = config['via-branch']['src-branch']
+        dst = config['via-branch']['dst-branch']
+    else:
+        userlog.error("Must specify either -f or -b command line option")
+        exit(1)    
 
     # Get the github sha corresponding to the specified mbed-os tag
-    cmd = ['git', 'rev-list', '-1', args.tag]
+    cmd = ['git', 'rev-list', '-1', tag]
     return_code, ref = run_cmd_with_output(cmd) 
 
     if return_code:
@@ -460,11 +481,7 @@ def create_work_directory(path):
         # Determine if this example should be updated and if so update any found 
         # mbed-os.lib files. 
 
-        # Only user or branch can be specified on the command line
-        if args.github_user:
-            result = upgrade_example(github, example, args.tag, ref, user=args.github_user)
-        else:
-            result = upgrade_example(github, example, args.tag, ref, branch=args.branch)
+        result = upgrade_example(github, example, tag, ref, user, src, dst)
 
         if result:
             successes += [example['name']]