diff --git a/.github/workflows/basic_testing.yaml b/.github/workflows/basic_testing.yaml index 44f5366..c1e47d3 100644 --- a/.github/workflows/basic_testing.yaml +++ b/.github/workflows/basic_testing.yaml @@ -68,6 +68,8 @@ jobs: - name: Install the code run: | cd $GITHUB_WORKSPACE + pip install pyyaml + ./jcb_client_init.py pip install .[testing] - name: Run unit tests diff --git a/.gitignore b/.gitignore index 952329a..98b30ce 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ +# JCB clients +src/jcb/configuration/algorithms/ +src/jcb/configuration/apps/gdas/ + # Mac files .DS_Store diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 5a0ba78..0000000 --- a/.gitmodules +++ /dev/null @@ -1,8 +0,0 @@ -[submodule "src/jcb/configuration/apps/gdas"] - path = src/jcb/configuration/apps/gdas - url = https://github.com/NOAA-EMC/jcb-gdas - branch = develop -[submodule "src/jcb/configuration/algorithms"] - path = src/jcb/configuration/algorithms - url = https://github.com/noaa-emc/jcb-algorithms - branch = develop diff --git a/README.md b/README.md index 11b905f..6c16519 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,12 @@ ### Installation ``` shell -git clone --recurse-submodules https://github.com/noaa-emc/jcb +git clone https://github.com/noaa-emc/jcb cd jcb + +# Optional step if you want to run the client integration tests +./jcb_client_init.py # May first require `pip install pyyaml` if it is not available + pip install --prefix=/path/to/where/you/want/installed . ``` diff --git a/get_submod_path.py b/get_submod_path.py deleted file mode 100644 index 789925a..0000000 --- a/get_submod_path.py +++ /dev/null @@ -1,55 +0,0 @@ -# -------------------------------------------------------------------------------------------------- - - -import configparser -import os -import sys - - -# -------------------------------------------------------------------------------------------------- - - -def parse_submodules_return_local_path(): - - # Path to submodule file - file_path = os.path.dirname(os.path.realpath(__file__)) - git_modules_file = os.path.join(file_path, '.gitmodules') - - config = configparser.ConfigParser() - config.read(git_modules_file) - - submodules = {} - for section in config.sections(): - submodule_name = section.split('"')[1].lower() - submodules[submodule_name] = { - 'path': config.get(section, 'path').lower(), - 'url': config.get(section, 'url').lower() - } - - return submodules - - -# -------------------------------------------------------------------------------------------------- - - -if __name__ == "__main__": - - # Get the repo path from the argument - submodule_repo = sys.argv[1].lower() - - # Parse git submodule file into a dictionary - submodules_dict = parse_submodules_return_local_path() - - # Loop over submodules_dict and print when found - for submodule_name, submodule in submodules_dict.items(): - if submodule['url'] == submodule_repo: - repo_found = True - # Export environment variable for path to repo - print(submodule['path']) - exit(0) - - # Fail if we got to here - exit(1) - - -# -------------------------------------------------------------------------------------------------- diff --git a/jcb_client_init.py b/jcb_client_init.py new file mode 100755 index 0000000..07fa62f --- /dev/null +++ b/jcb_client_init.py @@ -0,0 +1,252 @@ +#!/usr/bin/env python + + +# -------------------------------------------------------------------------------------------------- + + +import os +import subprocess +import typing + +import yaml + + +# -------------------------------------------------------------------------------------------------- + + +bold = '\033[1m' +red = '\033[91m' +green = '\033[92m' +end = '\033[0m' + + +# -------------------------------------------------------------------------------------------------- + + +def write_message(message: str, center: bool = False) -> None: + + """Write a message, optionally centered, and print it line by line. + + Args: + message (str): The message to be written and printed. + center (bool): If True, center each line of the message. Defaults to False. + """ + + # Max line length + max_line_length = 100 + + # Break the message into a list of lines max 100 characters but do not cut a word in half + lines = [] + while len(message) > max_line_length: + last_space = message[:max_line_length].rfind(' ') + lines.append(message[:last_space]) + message = message[last_space+1:] + lines.append(message) + + # If center is true center the lines + if center: + lines = [line.center(max_line_length) for line in lines] + + # Remove any lines that are empty + lines = [line for line in lines if line != ''] + + # Print the lines + for line in lines: + print(line) + + +# -------------------------------------------------------------------------------------------------- + + +def get_jcb_branch() -> typing.Optional[str]: + + """Get the current Git branch name. + + Executes a Git command to retrieve the current branch name. + Returns the branch name unless it is 'HEAD' or 'develop', + in which case it returns None. + + Returns: + Optional[str]: The current Git branch name, or None if the branch + is 'HEAD', 'develop', or if an error occurs. + """ + + # Command to get git branch + git_branch_command = ['git', 'rev-parse', '--abbrev-ref', 'HEAD'] + + # Return current branch + try: + branch = subprocess.check_output(git_branch_command).strip().decode('utf-8') + return branch if branch != 'HEAD' and branch != 'develop' else None + except subprocess.CalledProcessError: + return None + + +# -------------------------------------------------------------------------------------------------- + + +def branch_exists_on_remote(git_ls_remote_command: typing.List[str]) -> bool: + + """Check if a branch exists on the remote repository. + + Executes a Git command to check for the existence of a branch + on the remote repository. + + Args: + git_ls_remote_command (List[str]): The Git command to list remote branches. + + Returns: + bool: True if the branch exists on the remote repository, False otherwise. + """ + + # Return status of branch existence + try: + output = subprocess.check_output(git_ls_remote_command) + return bool(output) + except subprocess.CalledProcessError: + return False + + +# -------------------------------------------------------------------------------------------------- + + +def update_default_refs(jcb_apps: typing.Dict[str, typing.Dict[str, typing.Any]]) -> None: + + """Update the default Git references for jcb apps based on the current branch. + + Gets the current branch of the jcb repo and updates the default branch + for each app in jcb_apps if the branch exists on the remote. + + Args: + jcb_apps (Dict[str, Dict[str, Any]]): A dictionary containing app configurations, + where the key is the app name and the value is a dictionary with configuration details. + + Returns: + None + """ + + # Get the current branch of the jcb repo + jcb_branch = get_jcb_branch() + + # Nothing to do unless there is a branch called something other than develop + if jcb_branch is None: + return + + # Write message + write_message(f'The branch for jcb is {red + jcb_branch + end}. Looking for this branch ' + 'for the clients.') + + # Loop over jcb_apps and update default branch + for app, app_conf in jcb_apps.items(): + + # Check if the default branch exists + full_url = f'https://github.com/{app_conf["git_url"]}.git' + git_ls_remote_command = ['git', 'ls-remote', '--heads', full_url, jcb_branch] + + # If the branch exists, update the default branch + found = red + 'not found' + end + if branch_exists_on_remote(git_ls_remote_command): + found = green + 'found' + end + app_conf['git_ref'] = jcb_branch + write_message(f' Branch {jcb_branch} {found} for {app}') + write_message(' ') + + +# -------------------------------------------------------------------------------------------------- + + +def clone_or_update_repos(jcb_apps: typing.Dict[str, typing.Dict[str, typing.Any]]) -> None: + + """Clone or update repositories based on the provided configuration. + + Loops over jcb_apps and clones the repositories if the target path does not exist. + If the repository already exists at the target path, it prints a warning message. + + Args: + jcb_apps (Dict[str, Dict[str, Any]]): A dictionary containing app configurations, + where the key is the app name and the value is a dictionary with configuration details. + + Returns: + None + """ + + # Loop over jcb_apps and clone or update the repositories + for app, app_conf in jcb_apps.items(): + + target_path = app_conf['target_path'] + + # Check if the target path exists + if not os.path.exists(target_path): + + # Clone command + full_url = f'https://github.com/{app_conf["git_url"]}.git' + git_clone = ['git', 'clone', full_url, '-b', app_conf['git_ref'], + target_path] + + # Clone the repository + command_string = ' '.join(git_clone) + write_message(f'Cloning {app} with command: {command_string}') + subprocess.run(git_clone, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + + else: + + # Print warning that repo is already cloned + write_message(f'Repository {app} already cloned at {target_path}. Update ' + 'manually or remove to clone again using this script.') + + write_message(' ') + + +# -------------------------------------------------------------------------------------------------- + + +if __name__ == "__main__": + + # Write initial message + write_message(' ') + write_message('-'*100) + write_message(' ') + write_message(bold + 'Running jcb client initialization script' + end, True) + write_message(' ') + write_message('This script will clone any of the jcb clients that are registered in ' + 'jcb_apps.yaml.\n') + + # Get the path of this file + file_path = os.path.dirname(os.path.realpath(__file__)) + + # Open the jcb_apps.yaml file + with open(os.path.join(file_path, 'jcb_clients.yaml')) as file: + jcb_apps = yaml.load(file, Loader=yaml.FullLoader) + + # Required keys + required_keys = ['git_url', 'git_ref'] + + # Set the path to where the applications will be cloned + jcb_config_path = os.path.join(file_path, 'src', 'jcb', 'configuration') + + # Loop over jcb_apps and make sure required keys are present and add target_path + for app, app_conf in jcb_apps.items(): + for key in required_keys: + if key not in app_conf: + raise Exception(f'Key \'{key}\' not found in jcb_apps.yaml') + app_conf['target_path'] = os.path.join(jcb_config_path, 'apps', app) + + # Add jcb-algorithms to the dictionary + jcb_apps['algorithms'] = { + 'git_url': 'noaa-emc/jcb-algorithms', + 'git_ref': 'develop', + 'target_path': os.path.join(jcb_config_path, 'algorithms') + } + + # Update the default refs for the clients + update_default_refs(jcb_apps) + + # Clone or update the repositories + clone_or_update_repos(jcb_apps) + + write_message('Initialization of jcb clients is complete') + write_message(' ') + write_message('-'*100) + + +# -------------------------------------------------------------------------------------------------- diff --git a/jcb_client_path.py b/jcb_client_path.py new file mode 100755 index 0000000..4f2487f --- /dev/null +++ b/jcb_client_path.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python + + +# -------------------------------------------------------------------------------------------------- + + +import os +import sys + +import yaml + + +# -------------------------------------------------------------------------------------------------- + + +if __name__ == "__main__": + + # Get the repo path from the argument + git_url_in = sys.argv[1] + + # Get the path of this file + file_path = os.path.dirname(os.path.realpath(__file__)) + + # Open the jcb_apps.yaml file + with open(os.path.join(file_path, 'jcb_clients.yaml')) as file: + jcb_apps = yaml.load(file, Loader=yaml.FullLoader) + + # Loop over jcb_apps and make sure required keys are present and add target_path + for app, app_conf in jcb_apps.items(): + if git_url_in.lower() == app_conf['git_url'].lower(): + print(os.path.join(file_path, 'src', 'jcb', 'configuration', 'apps', app)) + exit(0) + + # Fail if we got to here + exit(1) + + +# -------------------------------------------------------------------------------------------------- diff --git a/jcb_clients.yaml b/jcb_clients.yaml new file mode 100644 index 0000000..5181737 --- /dev/null +++ b/jcb_clients.yaml @@ -0,0 +1,3 @@ +gdas: + git_url: noaa-emc/jcb-gdas + git_ref: develop diff --git a/src/jcb/configuration/algorithms b/src/jcb/configuration/algorithms deleted file mode 160000 index df03b11..0000000 --- a/src/jcb/configuration/algorithms +++ /dev/null @@ -1 +0,0 @@ -Subproject commit df03b11da1701f1713959f9ffc29dd2ba66efe62 diff --git a/src/jcb/configuration/apps/README.md b/src/jcb/configuration/apps/README.md new file mode 100644 index 0000000..82851c7 --- /dev/null +++ b/src/jcb/configuration/apps/README.md @@ -0,0 +1,30 @@ + +# Application client directory + +This directory represents the default location for the jcb application clients. If users run `jcb/jcb_init.py` the repos for the registered clients will be cloned to this directory and this will enable `jcb` to be tested with the clients. + +Clients have to be registered with jcb in a few steps: + +- Update `jcb/jcb_apps.yaml` at the top level of the repo to provide the Git address and the default 'ref', which could be branch, tag or commit hash. The new entry should look something like the following: + +```yaml +: + git_url: / # Do not append with .git + git_ref: develop # Branch, tag or hash +``` + +- Update `jcb/.gitignore` with `src/jcb/configuration/apps//`, where `` is the dictionary key used in `jcb_apps.yaml`. +- Add testing files like `jcb/test/client_integration/--templates.yaml`. These are the tests that will be run against changes to `jcb`. The more that users can provide here the better, since this protects the client against future changes to `jcb`. + +Optionally a client can be registered with `jcb` using `develop` as the default ref. Of course this poses risks for `jcb` because the client could move ahead of the core repo and cause tests to begin failing. However there is a benefit to the client to keep all the testing running against recent versions of the code without the headache of updating hashes in `jcb/jcb_apps.yaml`. Some cooperation is requested as a precursor for using `develop` as the default branch. + +- Add a run of the `jcb` client integration tests in the client. An example of this kind of test is shown here: https://github.com/NOAA-EMC/jcb-gdas/blob/develop/.github/workflows/run_jcb_basic_testing.yaml. That test can be copied verbatim to the other client repos since the script nowhere references the name of the client. +- Add branch protection in the client to prevent merging of anything to `develop` that does not satisfy the client testing of `jcb`. + +Note that from time-to-time there will the need to sync merges between `jcb` and all the clients and nothing in the above should prevent this. The extra testing added to the client checks for matching branch names. + +If a client becomes responsible for repeated test failures `jcb/jcb_apps.yaml` will be changed to use a recent hash. + +**_NOTE:_** +It would clearly simplify the above if clients were added to `jcb` as submodules. However, Git submodules are not permitted. While Git submodules are quite a powerful utility they are not always appropriate, especially when users might want more control of what is cloned and where. This is especially true as code gets closer to operations and operational workflows, and `jcb` is tightly integrated with these kinds of systems. + diff --git a/src/jcb/configuration/apps/gdas b/src/jcb/configuration/apps/gdas deleted file mode 160000 index 77f9e12..0000000 --- a/src/jcb/configuration/apps/gdas +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 77f9e126f47b0f5751ae0cf4f811629e99be7532