Page Comparison

This page is for integrators who will be bringing in code or changes to code from an external repository. This page describes the process where the code will be integrated into the ACME repository as a git subtree. There are three four possible workflows; Inserting in a new external to into ACME as a subtree, replacing original ACME code with an external subtree, and merging in changes from an external into an ACME subtree, and pulling changes from an ACME subtree to merge back to an external. Each workflow is outlined below followed by sections showing details for various workflow step types. Read the conditions at the top of each workflow to be sure to choose the correct one.

Some Terminology

<external-subdir> refers to the place in the ACME tree where the external code resides (or will reside).

...

<external_commit> refers to a branch name (<external_url>/<branch_name>), a commit, or a tag name from the external repository.

...

Insert new external subtree into ACME (one-time setup)

This workflow should only be used if ACME decides to adopt code from a new external. The resulting subtree will be a new subdirectory within ACME. This will typically be done once to be followed by the 'Merge Changes' workflow below.

1. Create and switch to a branch in which to conduct the work. Be sure to follow the branch naming conventions and other development practices. If the external code is to be completely replaced, create the branch from the commit where the code was last brought into the ACME repository (similar for the procedure for fixing a bug). The branch name should follow the form github-username/component/component.<version>_import.
2. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).
3. Add code from external git repo to ACME (git read-tree --prefix=<external_subdir>/ -u <external_commit>).
4. Commit the change (git commit).
5. Test and submit a pull request as defined in the development practices page.

...

Replace original (unmodified) ACME code with external subtree (one-time setup)

This workflow should only be used if original (v0.0) ACME code is being replaced with code from an external. This will typically be done once to be followed by the 'Merge Changes' workflow below.

1.  Verify that the external code in the ACME repository has been not been modified since the initial commit (cd <external-subdir>; git diff --name-only v0.0 .). If there are changes (non-blank output), follow the 'Merge changes from external into ACME subtree' workflow below.
2. Create and switch to a branch in which to conduct the work. Be sure to follow the branch naming conventions and other development practices. If the external code is to be completely replaced, create the branch from the commit where the code was last brought into the ACME repository (similar for the procedure for fixing a bug). The branch name should follow the form github-username/component/component.<version>_import.

3. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).

4. Remove the code from your working copy (git rm -r <external-subdir>).
5. Add code from external git repo to ACME (git read-tree --prefix=<external_subdir>/ -u <external_commit>).
6. Commit the change (git commit).
7. Test and submit a pull request as defined in the development practices page.

...

Merge changes from external into ACME subtree (typical workflow)

This workflow may be used repeatedly anytime new work is to be moved from an external into an ACME subtree.

1. Create and switch to a branch in which to conduct the work. Be sure to follow the branch naming conventions and other development practices. If the external code is to be completely replaced, create the branch from the commit where the code was last brought into the ACME repository (similar for the procedure for fixing a bug). The branch name should follow the form github-username/component/component.<version>_import.
2. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).
3. Merge  from external git repo to ACME (git merge --squash -X subtree=<external_subdir> --no-commit <external_commit>).
4. Commit the change (git commit).
5. Test and submit a pull request as defined in the development practices page.

...