Page Comparison

...

This page is for integrators who will be bringing in code or changes to code from an external repository or will be tasked with sharing some portion of ACME code externally. This page describes the process where the code will be integrated into the ACME repository as a git subtree. There are two workflows related to creating the initial git subtree within ACME:  Inserting in a new external into ACME as a subtree, replacing original ACME code with an external subtree.  There are two workflows for working with an established git subtree:  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. 

The `git subtree` command was introduced in version 1.7.11, so it's use requires at least that version.

Some Terminology

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

...

<external_url> is the URL for the external repository.

<external_repo> is the remote name for an external repo (or a fork of the external repo) that you have write access to. Note, it might be the same as <external_name>, but in the event you don't have write access to that repo, it will be different.

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

...

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. 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 in a subdirectory: (git
read
4. subtree add --
tree
5. squash --prefix=<external_subdir>
/ -u
6. <external_name> <external_commit>
).Commit the change (git commit
7. ).
8. Test and submit a pull request as defined in the development practices page.

...

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. 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>).

   1. Example:  git remote add -f --tags MCTorigin https://github.com/MCSclimate/MCT

   Remove the code from your working copy (git rm -r <external_subdir>).

4. Add code from external git repo to ACME in a subdirectory: (git
read
5. subtree add --
tree
6. squash --prefix=<external_subdir>
/ -u
7. <external_commit>).
   

   1. Example:  git 

read-tree

8. 1. subtree add --prefix=models/utils/mct/

-u

9. 1.  MCT_2.9.0-rc0

10. Check your work (git status)
11. Commit the change (git commit).
12. Test and submit a pull request as defined in the development practices page.

...

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. 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 subtree merge --squash -X subtree-prefix=<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.

...

Split changes from an ACME subtree for merging with an external repo

NOTE:  If you have to edit code that is in a subtree, commit those separately from other changes.

This workflow is to be used any time changes to an ACME subtree should be shared with the source external repository. For example, consider a bug fix made in the ACME MCT code. This workflow would allow contributing that fix upstream to MCT. Note that this workflow should not be used for the case where the ACME subdirectory was not brought into ACME as a subtree. That workflow is beyond the scope of this document.

1. Pull changes from the ACME subtree into a new branch (git subtree split -P <external_subdir> -b <external_branchname>).
   1. NOTE:  if the external_subdir has received more then one merge from the external, add --ignore-joins to the above.
2. If necessary, add remote for updated external (If git remote does not list your remote, add it with git remote add -f --tags <external_name> <external_url>).Push the branch to the remote repository (git push -u <external_name> <external_mergebranch>).
   1. Switch to your remote and create a new branch for merging ( git checkout <external_name>/master; git checkout -b <external_mergebranch>).
   2. Merge the changes from your subtree into your new branch (git merge <external_branchname>).
   3. 1. Similarly, add a remote for <external_repo> if different from <external_name>
   4. Push your branch to the external's repo, in preparation of merging following their workflow: (git push <external_repo> <external_branchname>)
   5. Follow other procedures for updating the external (depending on that external's workflow).

   ...