Skip to content

Developing Multiple Dependent Projects

Jump to bottom
Paul Mansour edited this page May 13, 2020 · 1 revision

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

Before merging a feature branch back into the master branch, all tests should be executed and pass. If any test breaks or fails, the code should be fixed, and the tests re-executed. This should be repeated as necessary until all tests pass. It is possible that other feature branches have been merged into the master in the meantime, and that the merge may fail and the feature branch must be rebased to the master. If this is the case, after rebasing, the tests should be run again. If there is a high probability that rebasing will necessary, the rebase should be done first to avoid running and potentially fixing the tests twice.

By definition, for the primary project, the tests are run on a feature branch that will be fast-forward merged to the master. If there are no dependencies, or if all the dependencies are loaded as packages, then the workspace is in the proper state for running tests before merging to the master.

If, however, some of the dependencies are loaded as projects, which is generally the case when developing projects in tandem, the workspace may not be in the proper state. The dependencies opened as projects may be in any state.

Developing multiple dependent projects simultaneously poses challenges. A new feature may be desired in the primary project A which in turn requires an enhancement to the dependent project B. Alternatively it may be desirable to enhance the dependent project B which necessitates changes to the primary project A if A wants to stay up with the latest version of B. In either case, changes to A and B may done simultaneously or B may done first. If developing the changes simultaneously we may run tests or create release artifacts (builds) using the current state of the workspace. At some point point both feature branches of A and B may be merged to their respective master branches . This process may repeat itself multiple times before releasing new version of either B or A. Thus we will have two projects whose master branches stay in sync, both of which have unreleased commits stacked up.

Note that it is important that if two projects are co-developed, then all developers working on the primary project must have have the dependent project cloned as a local sibling repository. The master branch of the primary project requires the most recent commit on the master of the dependent project - it cannot rely on the last release - that is, on a package.

When we decide to do a release, the dependent project B must be released first, and then the primary project A must then be updated to the specified version of B, and then a new version of A may be released.

If two projects can be combined into one, it can make things much simpler. However there are many reasons to have separate repositories. For example, we may want to opensource a dependency, while keeping a primary project proprietary. When the number of co-developed dependencies grows large, keeping them all in sync becomes a big problem. In fact, companies like Google and Facebook use single, massive "monorepos". While this makes some things easier, it makes many other things more difficult, and requires additional tooling.

To keep this manageable, the DependencyReport command displays the versioned state of the dependencies (the states used in a versioned build) and the current state of the dependencies (the states used in a non-versioned build) in the workspace. In this example, the parent project FlipDBDesktop has been opened without the -f parameter, thus loading sibling cloned dependencies as projects, not packages:

      ]AcreTools.DependencyReport
┌────────────────────────────────────────────────────────────────────────────┐
│ FlipDBDesktop Dependency Report                                            │
├────────────────────────────────────────────────────────────────────────────┤
│               Specified  Loaded   Current       New           Unreleased   │
│   Dependency  Version    Version  Branch        Version       Commits      │
│  ------------------------------------------------------------------------  │
│   *FlipDB     2.0.21     2.0.22   !feature/WIP  Yes (2.0.22)  Yes (3)      │
│   *Rumba      0.1.6      ←         master                                  │
│    XL2APL     0.0.13     ←         n/a                        ?            │
│   *CashFlow   2.0.5      ←         master                                  │
├────────────────────────────────────────────────────────────────────────────┤
│ * Locally cloned project (vs package)                                      │
│ ! Uncommitted changes                                                      │
│   Current workspace state is **NOT** safe for testing for release.         │
└────────────────────────────────────────────────────────────────────────────┘

For each dependency, the dependency report displays:

  • Dependency: The name of the dependency, preceded by an asterisk if the dependency is loaded from a local clone of the project rather than a package.
  • Specified Version: The version that will be used when doing a versioned build of the parent project or releasing a new version of the parent project.
  • Loaded Version: The version that is currently loaded in the workspace. For a package, this is, by definition, the same as the specified version. For a project, it may be a higher version.
  • Current Branch: The current branch of the project. For a package it is non-applicable (it is by definition the master).
  • New Version: The latest version available, if it differs from the specified version.
  • Unreleased Commits: The number of released commits for projects. For packages, this is unknown and not applicable.

While it is useful to test and build non-versioned artifacts at any time,
it is NOT safe to test and release a new version of the project unless for each co-developed project:

  1. The loaded version is the same as the specified version
  2. The current branch is the master and there are no uncommited changes on it
  3. There are no unreleased commits

Re-opening the parent project with the -f parameter to force dependencies to be loaded as packages rather than projects yields:

      ]AcreTools.DependencyReport
┌───────────────────────────────────────────────────────────────────────┐
│ FlipDBDesktop Dependency Report                                       │
├───────────────────────────────────────────────────────────────────────┤
│               Specified  Loaded   Current  New           Unreleased   │
│   Dependency  Version    Version  Branch   Version       Commits      │
│  -------------------------------------------------------------------  │
│    FlipDB     2.0.21     ←         n/a     Yes (2.0.22)  ?            │
│    Rumba      0.1.6      ←         n/a                   ?            │
│    XL2APL     0.0.13     ←         n/a                   ?            │
│    CashFlow   2.0.5      ←         n/a                   ?            │
├───────────────────────────────────────────────────────────────────────┤
│   Current workspace state is safe for testing for release.            │
└───────────────────────────────────────────────────────────────────────┘
Clone this wiki locally