git-tide 0.1.5__py3-none-any.whl

git_tide-0.1.5.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: git-tide
+Version: 0.1.5
+Summary: CLI for automated gitflow-style branching
+Project-URL: Homepage, https://github.com/chadrik/git-tide
+Author: Chad Dombrova, Matt Collie
+Requires-Python: >=3.8
+Requires-Dist: click==8.1.7
+Requires-Dist: commitizen==3.16.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Provides-Extra: init
+Requires-Dist: python-gitlab==4.8.0; extra == 'init'
+Description-Content-Type: text/markdown
+
+
+# Git Tide: Automated gitflow merge cycles with semantic versioning
+
+`tide` simplifies [gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) processes with automatic tagging and hot-fixing and promotion.
+
+## Features
+
+- Automatic cascading merging of hotfixes from stable branches into experimental ones, e.g. alpha, beta, rc (this is the "ebb tide")
+- - Automated "promotion" of experimental branches forward to their next branch.  e.g. alpha to beta, beta to rc, and so on. (this is the "flood tide" or "flow")
+- Uses [`commitizen`](https://github.com/commitizen-tools/commitizen) to create semver tags
+- Avoids merge conflicts between branches by using tags to store and query the latest version
+
+
+### Example flow
+
+Here is an overview of the rules that `tide` applies during automation:
+
+> NOTE: this document and repository use **develop**, **staging**, and **master** for it's gitflow branches 
+> but this behavior is configurable in the **pyproject.toml** and **.gitlab-ci.yml** files.
+
+- New features should start as merge requests made against the `develop` branch (this is the default branch)
+- Commits that are merged to `develop` auto-generate a tag with a beta suffix: e.g. `1.0.0b1`
+- Commits that are merged to `staging` auto-generate a tag with a release candidate suffix: e.g. `1.0.0rc1`
+- Hotfixes that are added to `master` automatically merge to `staging`
+- Hotfixes that are added to `staging` automatically merge to `develop`
+- Promoting the release candidate to a new official release can be done two ways:
+  - Every pipeline on the `staging` branch has a `promotion` job that can be manually run
+  - A scheduled pipeline can be setup to do the same
+- Either way, when the `promotion` job runs it will do 3 things:
+  - Move the `master` branch to the tip of `staging` and create a new release, stripping off the `rc` suffix
+  - Move the `staging` branch to the tip of `develop` and create a new release, converting `b` to `rc`
+  - Restart `develop`, incrementing the minor version, e.g. from `1.1.0b4` to `1.2.0b0`. 
+
+### Sample development cycle
+
+Below is the Git commit graph demonstrating a sample development cycle using this project's branching strategy, 
+including tags and hotfix propagation.
+
+```plaintext
+*   auto-hotfix into develop: staging: add hotfix 2 -  (HEAD -> develop, tag: 1.2.0rc0, tag: 1.2.0b2, staging)
+|\  
+| * staging: add hotfix 2 -  (tag: 1.1.0rc2, tag: 1.1.0, master)
+* | auto-hotfix into develop: master: add hotfix -  (tag: 1.2.0b1)
+|\| 
+| *   auto-hotfix into staging: master: add hotfix -  (tag: 1.1.0rc1)
+| |\  
+| | * master: add hotfix -  (tag: 1.0.1)
+* | | develop: add beta feature 2 -  (tag: 1.2.0b0)
+|/ /  
+* / develop: add feature 1 -  (tag: 1.1.0rc0, tag: 1.1.0b0)
+|/  
+* master: initial state -  (tag: 1.0.0)
+
+chronological tag order:
+1.2.0rc0        promoting develop to staging!
+1.1.0           promoting staging to master!
+1.2.0b2         auto-hotfix into develop: staging: add hotfix 2
+1.1.0rc2        staging: add hotfix 2
+1.2.0b1         auto-hotfix into develop: master: add hotfix
+1.1.0rc1        auto-hotfix into staging: master: add hotfix
+1.0.1           master: add hotfix
+1.2.0b0         develop: add beta feature 2
+1.1.0rc0        promoting develop to staging!
+1.1.0b0         develop: add feature 1
+1.0.0           master: initial state
+```
+
+## Setting up a repo
+
+In order for `tide` to work its magic, the Gitlab repo needs to be properly configured:
+
+- Add a `[tool].tide` section to your `pyproject.toml` file to define the gitflow branch names and prerelease version you wish to use.
+    ```toml
+    [tool.tide]
+    branches.beta = "develop"
+    branches.rc = "staging"
+    branches.stable = "master"
+    ```
+- For each project within your repo that you want to manage tagged releases, add a `project` entry:
+    ```toml
+    [tool.tide]
+    project = "project_name"
+    ```
+  If there is only one, then combine be sure to put all of your options under a single `[tool.tide]` section.
+- Create a [Project Access Token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with the appropriate scope for being able to push tags, changes and create cicd variables.
+- Run `tide init --access-token='YOUR_ACCESS_TOKEN'`
+- Copy and modify the `.gitlab-ci.yml` file ensuring the branch variables match the ones in the `pyproject.toml` (TODO: automated generation of `.gitlab-ci.yml` in `tide init`)
+
+## Development
+
+### Setting up your local development environment
+
+- clone the repository using either https or ssh depending on your preference and then run the following commands:
+```bash
+python -m venv venv
+.\venv\Scripts\Activate
+pip install -r requirements.txt
+pre-commit install
+```
+
+### Local development info, tips, and tricks
+
+`nox` is the primary interface for what we'll be doing day to day and under the hood.
+
+Use `nox --list` to see the tasks that are available. 
+
+### Running the unit tests
+
+```bash
+nox -s unit_tests
+```
+
+The primary test `tests/test_unit.py::test_dev_cycle` can be run in several modes:
+- local: simulated using local repos
+- remote: integration testing using real gitlab repos
+- gitlab-ci-local: simulated using local repos, but using the `.gitlab-ci.yml` file for entry-point and env var control.  Requires installation of https://github.com/firecow/gitlab-ci-local
+
+Here's how you run it in remote mode:
+```bash
+EXEC_MODE="remote" ACCESS_TOKEN="your-access-token-here" nox -s unit_tests -- tests/test_unit.py::test_dev_cycle -vv -s
+```
+
+Here's how you run it using `gitlab-ci-local`:
+```bash
+EXEC_MODE="gitlab-ci-local" nox -s unit_tests -- tests/test_unit.py::test_dev_cycle -vv -s
+```
+
+### Serving Documentation on GitLab Pages
+
+Our project leverages GitLab Pages to host and serve the documentation generated by MkDocs. This setup ensures that all team members and stakeholders have access to the most current documentation relevant to the entire project.
+
+#### How It Works
+
+- **Unified Documentation:** We maintain a single, comprehensive documentation system that reflects the latest changes in our codebase.
+
+- **Automated Builds:** The documentation is automatically built and updated whenever changes are made. This ensures that our documentation is always up-to-date with the latest codebase.
+
+#### Benefits
+
+- **Simplified Access:** Provides a single, consistent source of documentation for all stakeholders, simplifying access and reducing potential confusion.
+- **Immediate Updates:** Changes to the documentation are immediately reflected upon updates, ensuring that the documentation always matches the current state of the project.
+
+This streamlined approach to documentation allows our team to efficiently maintain and update project details, ensuring consistent and accessible information for everyone involved.

git_tide-0.1.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+tide/__init__.py,sha256=P976fB0eaD6inWZ19CcXgKWlqOQpp_anldhYxqpJqrw,55
+tide/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+tide/cli.py,sha256=Il3OzcMtsvAYx8YMmgMFb54wl3e6PMwzilU0SkodwUo,10182
+tide/core.py,sha256=zG9aQ1FCPSxRiI57JeqOAnX2eRl3P9bCTT-MMoPyxVE,26494
+tide/gitutils.py,sha256=7tRfuGRYPtDImFMUmGCIKd1BLxfpO40IMKLx-rnFhxs,9123
+git_tide-0.1.5.dist-info/METADATA,sha256=rX8ZJ4tPqX6xqAchb7GGfC0-CHbR0x3d0mycCUV65N4,7251
+git_tide-0.1.5.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+git_tide-0.1.5.dist-info/entry_points.txt,sha256=GcxqhKkWJnEGVaoKzpajCFCyeXa2Ga8da-UbInkFUJY,39
+git_tide-0.1.5.dist-info/RECORD,,

git_tide-0.1.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_tide-0.1.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tide = tide.cli:main

tide/__init__.py

@@ -0,0 +1 @@
+from __future__ import absolute_import, print_function

tide/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tide/cli.py

@@ -0,0 +1,349 @@
+from __future__ import absolute_import, print_function, annotations
+import click
+import time
+import os
+import subprocess
+import re
+from pathlib import Path
+
+from .core import (
+    is_url,
+    get_next_version,
+    get_current_version,
+    get_modified_projects,
+    get_projects,
+    load_config,
+    promote as _promote,
+    Config,
+    Runtime,
+    Backend,
+    GitlabBackend,
+    TestGitlabBackend,
+    GitlabRuntime,
+    TestGitlabRuntime,
+    LocalRuntime,
+    ENVVAR_PREFIX,
+    HOTFIX_MESSAGE,
+)
+from .gitutils import git, checkout
+
+CONFIG: Config
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+def set_config(config: Config) -> Config:
+    """
+    Set the global configuration object.
+    """
+    global CONFIG
+    CONFIG = config
+    return config
+
+
+def get_backend(url: str | None = None) -> Backend:
+    """
+    Return a Backend corresponding to where the current python process is pushing/pulling.
+    """
+    if os.environ.get("GITLAB_CI", "false") == "true" or (url and "gitlab" in url):
+        return GitlabBackend(CONFIG)
+    else:
+        return TestGitlabBackend(CONFIG)
+
+
+def get_runtime() -> Runtime:
+    """
+    Return a Runtime corresponding to where the current python process is *running*
+    """
+    if os.environ.get("GITLAB_CI", "false") == "true":
+        return GitlabRuntime(CONFIG)
+    # gitlab-ci-local and our unittests set this to false as an inidicator that
+    # we are testing gitlab, but not IN gitlab.
+    elif os.environ.get("GITLAB_CI") == "false":
+        return TestGitlabRuntime(CONFIG)
+    else:
+        return LocalRuntime(CONFIG)
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+@click.option("--config", "-c", "config_path", metavar="CONFIG", type=str)
+@click.option("--verbose", "-v", is_flag=True, default=False)
+def cli(config_path: str, verbose: bool) -> None:
+    set_config(load_config(config_path, verbose))
+
+
+@cli.command()
+@click.option(
+    "--access-token",
+    required=True,
+    metavar="TOKEN",
+    help="Security token used to authenticate with the remote",
+)
+@click.option(
+    "--remote",
+    default="origin",
+    metavar="REMOTE",
+    show_default=True,
+    help=(
+        "The name of the git remote in the current git repo "
+        "(e.g. configured using `git remote`) or the remote URL. "
+        "Providing a URL implies --no-local"
+    ),
+)
+@click.option(
+    "--save-token/--no-save-token",
+    default=True,
+    help="Whether to save the access token into the remote as a reusable "
+    "variable. If this is disabled, you must configure the ACCESS_TOKEN "
+    "manually.",
+)
+@click.option(
+    "--init-local/--no-local",
+    default=True,
+    help="Whether to initialize the local git repo",
+)
+@click.option(
+    "--init-remote/--no-remote",
+    default=True,
+    help="Whether to initialize the remote git repo (i.e. Gitlab)",
+)
+def init(
+    access_token: str,
+    remote: str,
+    save_token: bool,
+    init_local: bool,
+    init_remote: bool,
+) -> None:
+    """
+    Initialize the current git repo and its associated Gitlab project for use with tide.
+
+    This command must be run from a git repo, and the repo must have the Gitlab project setup
+    as a remote, either by being cloned from it, or via `git remote add`.
+    """
+    import tempfile
+
+    if is_url(remote):
+        init_local = False
+        remote_url = remote
+    else:
+        # FIXME: print a user friendly error if we're not in a git repo.
+        # FIXME: handle remote not setup correctly
+        remote_url = git("remote", "get-url", remote, capture=True)
+
+    backend = get_backend(remote_url)
+
+    if init_local:
+        backend.init_local_repo(remote)
+    else:
+        # we may still need to create branches in the remote, so create a dummy clone
+        with tempfile.TemporaryDirectory() as tmpdir:
+            git("clone", f"--branch={CONFIG.stable}", remote_url, tmpdir)
+            pwd = os.getcwd()
+            try:
+                os.chdir(tmpdir)
+                backend.init_local_repo("origin")
+            finally:
+                os.chdir(pwd)
+
+    # FIXME: add pyproject.toml section?  check if it exists?  Hard to do automatically,
+    #  because in a monorepo there could be many.
+    # FIXME: create a stub gitlab-ci.yml file if it doesn't exist?
+    if init_remote:
+        backend.init_remote_repo(remote_url, access_token, save_token)
+
+
+@cli.command()
+@click.option(
+    "--annotation",
+    default="automatic change detected",
+    show_default=True,
+    help="Message to pass for tag annotations.",
+)
+@click.option(
+    "--base-rev",
+    metavar="SHA",
+    help="The Git revision to compare against when identifying changed files.",
+)
+def autotag(annotation: str, base_rev: str | None) -> None:
+    """
+    Tag the current branch with a new version number and push the tag to the remote repository.
+    """
+    runtime = get_runtime()
+    branch = runtime.current_branch()
+    remote = runtime.get_remote()
+
+    backend = get_backend()
+
+    if not base_rev:
+        base_rev = runtime.get_base_rev()
+
+    projects = get_modified_projects(base_rev, verbose=CONFIG.verbose)
+    if projects:
+        for project_folder, project_name in projects:
+            # Auto-tag
+            tag = get_next_version(
+                CONFIG, remote, branch, project_name, project_folder, as_tag=True
+            )
+
+            # NOTE: this delay is necessary to create stable sorting of tags
+            # because git's time resolution is 1s (same as unix timestamp).
+            # https://stackoverflow.com/questions/28237043/what-is-the-resolution-of-gits-commit-date-or-author-date-timestamps
+            time.sleep(1.1)
+
+            click.echo(f"Creating new tag: {tag} on branch: {branch} {time.time()}")
+            git("tag", "-a", tag, "-m", annotation)
+
+            # FIXME: we may want to push all tags at once
+            click.echo(f"Pushing {tag} to remote")
+            backend.push(remote, tag)
+    else:
+        click.echo("No tags generated!", err=True)
+
+
+@cli.command()
+def hotfix() -> None:
+    """
+    Merge hotfixes from a feature branch back to upstream branches.
+    """
+    runtime = get_runtime()
+    branch = runtime.current_branch()
+    remote = runtime.get_remote()
+    upstream_branch = CONFIG.get_upstream_branch(branch)
+    if not upstream_branch:
+        click.echo(f"No branch upstream from {branch}. Skipping auto-merge")
+        return
+
+    # Auto-merge
+    # Record the current state
+    message = git("log", "--pretty=format: %s", "-1", capture=True)
+    # strip out previous Automerge formatting
+    match = re.match(
+        HOTFIX_MESSAGE.format(upstream_branch="[^:]+", message="(.*)$"), message
+    )
+    if match:
+        message = match.groups()[0]
+
+    git("checkout", "-B", f"{branch}_temp")
+
+    # Fetch the upstream branch
+    git("fetch", remote, upstream_branch)
+
+    checkout(remote, upstream_branch, create=True)
+
+    msg = HOTFIX_MESSAGE.format(upstream_branch=upstream_branch, message=message)
+    click.echo(msg)
+
+    try:
+        git("merge", f"{branch}_temp", "-m", msg)
+    except subprocess.CalledProcessError:
+        click.echo("Conflicts:", err=True)
+        git("diff", "--name-only", "--diff-filter=U")
+        raise
+
+    # this will trigger a full pipeline for upstream_branch, and potentially another auto-merge
+    click.echo(f"Pushing {upstream_branch} to {remote}")
+    variables = {
+        f"{ENVVAR_PREFIX}_AUTOTAG_ANNOTATION": msg,
+    }
+    get_backend().push(remote, upstream_branch, variables=variables)
+
+
+@cli.command()
+def promote() -> None:
+    """
+    Promote changes through the branch hierarchy.
+
+    e.g. from alpha -> beta -> rc -> stable.
+    """
+    backend = get_backend()
+    runtime = get_runtime()
+    remote = runtime.get_remote()
+    if CONFIG.verbose:
+        click.echo(f"remote = {remote}")
+    _promote(CONFIG, backend, runtime)
+
+
+@cli.command
+@click.option("--modified", "-m", is_flag=True, default=False)
+# FIXME: add output format
+# FIXME: add option to write to file
+def projects(modified: bool) -> None:
+    """
+    List project paths within the repo.
+
+    A project is a folder with a pyproject.toml file with a `tool.commitizen` section.
+    """
+    if modified:
+        runtime = get_runtime()
+        projects_ = get_modified_projects(
+            runtime.get_base_rev(), verbose=CONFIG.verbose
+        )
+    else:
+        projects_ = get_projects()
+
+    for project_dir, project_name in projects_:
+        if project_name is None:
+            project_name = "[unset]"
+        click.echo(f"{project_name} = {project_dir}")
+
+
+@cli.command
+@click.option(
+    "--path",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    show_default=True,
+    help="Folder within the repository. A pyproject.toml should reside in the "
+    "specified directory",
+)
+@click.option(
+    "--branch",
+    default=None,
+    help=(
+        "The release branch to use to determine the next version. "
+        "Defaults to the current branch."
+    ),
+)
+@click.option(
+    "--remote",
+    default="origin",
+    show_default=True,
+    help="The git remote to use to when determining the next version.",
+)
+@click.option("--next", "-n", is_flag=True, default=False)
+@click.option("--as-tag", "-t", is_flag=True, default=False)
+def version(
+    path: str, branch: str | None, remote: str, next: bool, as_tag: bool
+) -> None:
+    """
+    Get the project version
+    """
+    projects = dict(get_projects())
+    folder = Path(path)
+    try:
+        project_name = projects[folder]
+    except KeyError:
+        raise click.ClickException(
+            f"There is not a project at path={folder}. "
+            "Ensure there is a pyproject.toml file with a [tool.tide] section "
+            "and a `project` entry"
+        )
+
+    if next:
+        if branch is None:
+            runtime = get_runtime()
+            branch = runtime.current_branch()
+
+        click.echo(
+            get_next_version(CONFIG, remote, branch, project_name, folder, as_tag)
+        )
+    else:
+        click.echo(get_current_version(CONFIG, project_name, folder, as_tag))
+
+
+def main() -> None:
+    import shutil
+
+    return cli(
+        auto_envvar_prefix=ENVVAR_PREFIX,
+        max_content_width=shutil.get_terminal_size().columns,
+    )