Source Control
- Ray Lee (Unlicensed)
Source code for UCB CollectionSpace customizations is managed using git, and is hosted on github, within the cspace-deployment organization.
Project Organization
UCB customizations to CollectionSpace reside in three projects: services, application, and ui, which contain customizations to the services layer, application layer, and UI layer, respectively. Each project is a fork of the identically named project in the collectionspace organization.
| Project | Forked from | Description |
|---|---|---|
| cspace-deployment/services | collectionspace/services | Contains customizations to the CollectionSpace services layer. This includes schema extensions (pre-4.0), custom validator handlers, custom Nuxeo event handlers, custom SQL scripts, and bug fixes and functional enhancements not yet contributed back to the CollectionSpace project. |
| cspace-deployment/application | collectionspace/application | Contains customizations to the CollectionSpace application layer. This includes field-level configuration changes, domain- and tenant-level extensions, and bug fixes and functional enhancements not yet contributed back to the CollectionSpace project. |
| cspace-deployment/ui | collectionspace/ui | Contains customizations to the CollectionSpace UI layer. This includes customizations to HTML forms, CSS stylesheets, and message strings, and bug fixes and functional enhancements not yet contributed back to the core CollectionSpace project. |
Branch Organization
The three projects in cspace-deployment contain similar branch structures:
| Branch | Upstream Branch | Description | |
|---|---|---|---|
| cspace-deployment/master | collectionspace/master | The master branch contains customizations to the currently under-development (unreleased) version of CollectionSpace. It is downstream from the master branch in the corresponding project from collectionspace. The customizations in this branch are shared by all UCB deployments; they are not specific to any particular museum. In practice, code in this branch tends to languish behind the code in its upstream branch, and behind the customizations in the latest vN.N branch. Active development takes place in the latest N.N branches (described below). Occasionally (usually right before or after a CollectionSpace release, during the process of upgrading the UCB deployments to the latest release) this branch is brought up to date by merging in collectionspace/master and the latest vN.N branch. | |
| cspace-deployment/vN.N | collectionspace/vN.N | (For example: v4.0). Each vN.N branch contains customizations to the numbered release of CollectionSpace. These customizations are shared by all UCB deployments. Every vN.N branch lies downstream from the identically named vN.N branch in the corresponding project from collectionspace, thus inheriting all of the core code for that release of CollectionSpace. The customizations in these branches are used by all UCB deployments; they are not specific to any particular museum. Active development takes place in the latest vN.N branch, and the latest deployment-specific N.N branches, which are described below. | |
| cspace-deployment/pahma_N.N | cspace-deployment/vN.N | (For example: pahma_4.0). Each pahma_N.N branch contains customizations to the numbered release of CollectionSpace, specifically for the Phoebe A. Hearst Museum of Anthropology. Every pahma_N.N branch lies downstream from the vN.N branch with the same number, thus inheriting the core CollectionSpace code for that version, and the shared UCB customizations for that version. pahma_N.N contains tenant-specific customizations on top of those shared customizations. | |
| cspace-deployment/ucjeps_N.N | cspace-deployment/vN.N | (For example: ucjeps_4.0). Each ucjeps_N.N branch contains customizations to the numbered release of CollectionSpace, specifically for the UC and Jepson Herbaria. Every ucjeps_N.N branch lies downstream from the vN.N branch with the same number, thus inheriting the core CollectionSpace code for that version, and the shared UCB customizations for that version. ucjeps_N.N contains tenant-specific customizations on top of those shared customizations. | |
| cspace-deployment/botgarden_N.N | cspace-deployment/vN.N | (For example: botgarden_4.0). Each botgarden_N.N branch contains customizations to the numbered release of CollectionSpace, specifically for the UC Botanical Garden. Every botgarden_N.N branch lies downstream from the vN.N branch with the same number, thus inheriting the core CollectionSpace code for that version, and the shared UCB customizations for that version. botgarden_N.N contains tenant-specific customizations on top of those shared customizations. | |
| cspace-deployment/cinefiles_N.N | cspace-deployment/vN.N | (For example: cinefiles_4.0). Each cinefiles_N.N branch contains customizations to the numbered release of CollectionSpace, specifically for the CineFiles collection of the Pacific Film Archive. Every cinefiles_N.N branch lies downstream from the vN.N branch with the same number, thus inheriting the core CollectionSpace code for that version, and the shared UCB customizations for that version. cinefiles_N.N contains tenant-specific customizations on top of those shared customizations. | |
| cspace-deployment/bampfa_N.N | cspace-deployment/vN.N | (For example: bampfa_4.0). Each bampfa_N.N branch contains customizations to the numbered release of CollectionSpace, specifically for the art collection of the Berkeley Art Museum/Pacific Film Archive. Every bampfa_N.N branch lies downstream from the vN.N branch with the same number, thus inheriting the core CollectionSpace code for that version, and the shared UCB customizations for that version. bampfa_N.N contains tenant-specific customizations on top of those shared customizations. |
Other branches exist, but are not normally used during development of UCB customizations, so they are not mentioned here. Some of these branches are inherited from the corresponding collectionspace project; others are temporary, or legacy, branches.
For clarity, the shared UCB customization branches (e.g. cspace-deployment/master, cspace-deployment/v4.0) maintain the same names as their upstream branches in the collectionspace projects. Similarly, the tenant-specific customization branches (e.g. cspace-deployment/pahma_4.0, cspace-deployment/ucjeps_4.0) are each named by the tenant id, and the number of the upstream branch. Since deployments are only based on released versions of CollectionSpace (and never on unreleased code from the master branches in collectionspace), there are no branches with names like cspace-deployment/pahma_master, or cspace-deployment/ucjeps_master. When a new release of CollectionSpace is branched in the collectionspace project, only then is a new tenant-specific N.N branch created, to hold customizations based on that release of CollectionSpace.
In the future, we may set up a continuous integration process where tenant customizations (from the latest tenant-specific vN.N branch) are automatically merged with the latest code from master, and tested, on a regular schedule. This would alert us to potential upgrade problems before the next version of CollectionSpace is released. If this happens, tenant-specific master branches may be created. However, active development will continue only to occur on the latest vN.N branches.
Working with Branches
Upstream branches should be merged into downstream branches on a regular basis, in order to keep the downstream branches up to date. For example, in each project, collectionspace/v4.0 should be merged into cspace-deployment/v4.0 regularly (although in practice, the collectionspace release branches see very little activity, so this isn't done often). Similarly, cspace-deployment/v4.0 should be merged into cspace-deployment/pahma_4.0, cspace-deployment/ucjeps_4.0, etc., fairly frequently.
Downstream branches should never be merged into upstream branches. For example, cspace-deployment/cinefiles_4.0 should never be merged into cspace-deployment/v4.0. This would cause CineFiles-specific customizations to go into the branch for shared customizations. Similarly, cspace-deployment/v4.0 should never be merged into collectionspace/v4.0. This would cause UCB customizations to go into the core CollectionSpace project. There are times when a customization initially implemented for a single tenant is deemed useful for all tenants, or when a UCB shared customization is contributed to the core CollectionSpace project. In these cases, it may be appropriate to cherry-pick individual commits from the downstream branch into the upstream branch.
The N.N branches on cspace-deployment (e.g. v4.0, pahma_4.0, bampfa_4.0) should be considered release branches. It should be assumed that those branches may be tagged and deployed to production at any time. Code should be committed to those branches only if there is reasonable confidence that it is ready to go into production. Works in progress should be done in separate branches, and merged into the N.N branches only when complete.
Care should be taken to ensure that tenant-specific customizations are committed to a tenant-specific branch, and that shared customizations are committed to the shared customization branch. For example, if the current version of CollectionSpace is 4.0, customizations intended only for the CineFiles tenant should be committed only to cspace-deployment/cinefiles_4.0. Customizations intended for all tenants should be commited to cspace-deployment/v4.0, so that they may be merged into all of the downstream tenant-specific branches. In the application and UI layers, it's easy to tell which is which. Files in the defaults directory are meant to be shared, and files under tenants are meant only for specific tenants. So changes to files under defaults should be committed to a shared customization branch, and changes to files under tenants should be committed to the appropriate tenant-specific customization branch.
Tagging and Releasing
Updates to UC Berkeley's customized CollectionSpace deployments tend to be small, frequent, and low-risk. (The one big exception to this is when a new version of CollectionSpace is released, and all tenants need to be upgraded – this process will be covered in a separate document). Because of this, it's normal to follow a streamlined release process:
- Tag the tenant-specific N.N branch. The release tag should contain the name of the branch being tagged, followed by a dash, followed by the number of the release, which should be incremented by one for each release. For example,
pahma_4.0-23. - Deploy the tag to a dev server, and test.
- Deploy the tag to a production server.
This process works well when the QA period on the dev server lasts less than a day, which is true for the vast majority of releases.
Older release tags used a different pattern with more long-winded tags containing dates, e.g. deploy-to-pahma-2014-06-02, but future releases should use the above pattern.
Occasionally, updates may contain many changes, or may contain high-risk changes, and will require a longer period of testing and bug-fixing. In these cases, the full release process should be used:
- From the tenant-specific N.N branch, create a release branch (instead of a tag). A release branch should follow the same naming convention as a release tag, e.g.
pahma_4.0-23. - Deploy the branch to a dev server, test, and fix bugs. Repeat until no more bugs are found. All bug fixes will also have to be applied to the N.N branch.
- Tag the branch. The tag should be named the same as the branch.
- Deploy the tag to a production server.
This allows development on future releases to continue on the N.N branch, while QA is done on the release branch. During this time any bug fixes made to the release branch will also have to be applied to the N.N branch.
There may be times when a critical bug fix needs to be made to the current release. Usually, the bug fix can be made to the N.N branch, and the streamlined release process may be used to tag a new release containing the bug fix. However, if the N.N branch contains many changes, or contains high-risk changes that would require a long QA period before release, the bug fix may not be able to wait. In that case, the following bug fix update process may be used:
- If there is not already branch for the current release (in other words, the current release was made using the streamlined release process), create a branch from the tag, with the same name as the tag.
- Make the bug fix in the release branch. The fix will also have to be applied to the N.N branch.
- Deploy the branch to a dev server, and test.
- Tag the branch. The new tag should contain the name of the branch, followed by a dot, followed by the number of the bug fix update, which should be incremented by one for each update. For example,
pahma_4.0-23.1. - Deploy the tag to a production server.