# Merge back GT4Py `functional` branch in `main`

###### tags: `functional cycle 13`

- Developers: Enrique
- Appetite: 2 weeks

## Problem

There are currently two completely independent versions of the GT4Py framework: **cartesian** (v1.x, branch: [main](https://github.com/GridTools/gt4py/tree/main)) and **functional** (v0.2.x, branch: [functional](https://github.com/GridTools/gt4py/tree/functional)) living in different branches of the GT4Py repository. Most of the incompatibilities between both branches have been fixed in the preparatory work for the first public release of the v1.x branch, therefore, it should be now relatively straightforward to merge back both branches together, to support workflows where users mix both versions in the same project.

## Goals

This project will merge the `functional` version of GT4Py as a `gt4py.experimental` subpackage in the `main` branch.

## Non-goals

Cleaning up code or adding new features like making `gt4py.storage` compatible with the the current `functional` version is completely out of scope.

## Known steps

The following list of steps describes a reasonable workflow to have both branches merged. In most of the merge conflicts specifically one of the two branches has a more up-to-date version and it should be used as the _base_ content, and required changes from the other branch should be added on top of it. Additionally, some tool configurations should be upgraded to the current stable versions and get rid of deprecated configurations (e.g. `setup.cfg`).

1. Merge the contents of `functional` in main following the existing repository layout:

    .github/    [base: functional]
    .gitpod/    [base: functional] 
    .ci/        [base: functional] 
    examples/   
    src/        [base: main]
        gt4py/
            cartesian/
            experimental/    [<== functional:src/functional, removing top-level files]
            eve/
            storage/
            ...
    tests/      [base: main] 
        cartesian_tests/
        experimental_tests/  [<== functional:tests/functional_tests, 
        eve_tests/
        storage_tests/
        conftest.py          [join both branches and refactor if needed]

    CONTRIBUTING/README/GUIDELINES   [base: functional]
    LICENSE*                         [base: main]
    .pre-commit-config.yaml          [base: functional]
    .setup.cfg => pyproject.toml     [move configs to pyproject.toml and delete setup.cfg]
    tox.ini                          [base: functional]    

This step includes renaming of folders and files and update code references.

2. Fix **eve** conflicts between branches using `main` as base and adopting the minimum number of extra features and fixes from `functional`.

3. Fix failing tests, if any.

4. Update Python package definition and move it from `setup.cfg` to `pyproject.toml` (maybe updating the required version of `setuptools`).

5. Update configuration of local development tools:
- **flake8** and **mypy**: migrate configs to `pyproject.toml` using `functional` branch as base version, cherry pick required changes from `main`.
- **pre-commit**: use `functional` branch as base version and cherry pick required changes from `main`.
- **tox**: update config to current stable version (v4.x) and merge both branches using `functional` as base.
- Versioning/releasing (currently `bump2version`) tools: use `main` as base and merge changes from `functional`.
- (Optional) automatize new version releases with other tools including more features like `Changelog` generation (`git-changelog`, `towncrier`, `commmitizen`, etc.). Note that some of them might be able to fully replace `bumpversion`.

7. Unify developer documentation files (README, CODING_GUIDELINES, CONTRIBUTING, CHANGELOG, ...) using `functional` branch as base version and cherry pick required changes from `main`.

8. Merge documentation files and `sphinx` configuration.

## Possible rabbit holes

Finding settings of the development tools compatible with both branches (e.g. `mypy`, `flake8`) and setting up all the existing automated workflows (locally with `tox` and hosted on GitHub CI) may take longer than expected and require a lot of time-consuming trial and error.