Using External Synchronization (best practice)
| Table of contents |
This chapter describes best practice cases for using External Synchronization in a distributed development environment.
The steps described in the following apply to the developers and must be performed each time content is edited. It is important to make sure that the Import and Export steps in particular are performed after modification in order to ensure data consistency.
The individual steps describe how project content is imported, modified, and exported between the file system and a FirstSpirit project. The process for managing and merging all changes is supported by a version control system.
Conflicts that occur at different points during distributed development and that are not automatically dealt with by the version control system are described in the Resolving conflicts chapter along with specific scenarios and suggested solutions.
Step-by-step workflow
1) Update
From the repository to the file system (via VCS)
Distributed development is based on a foundation of one FirstSpirit instance (or a central development state). The central development state is made available to all developers involved via a remote repository. Within his own local development environment, each developer also works with his own local repository.
At the start of each template editing process, the developer must collect the current state from the remote repository. In this process, all changes are first downloaded from the central repository (e.g., in Git via “fetch”) and then merged with the state in the local repository. The versioned content from the local repository is transferred into the target folder (“Sync Dir”) in the local file system (e.g., in Git via “checkout” or “pull”). During this process, external changes (made by other developers) are merged with the developer’s own local changes (“merge”)
For further information, see Update.
 |
Notes on conflict handling: Conflicts may occur when updating, particularly when merging changes. Possible conflicts and solution strategies are described under Conflict handling. |
2) Import
From the file system to the FirstSpirit project (via External Synchronization)
In the second step, the project’s current development state is imported out of the file system into the local FirstSpirit project instance using FSDevTools (fs-cli import). During this process, objects are created, updated, moved, and deleted within the project.
For further information, see Import.
3) Modification
Template development in FirstSpirit (using SiteArchitect)
In step 3, the templates themselves are developed. The developer edits the templates or referenced elements, creates new templates, or deletes existing elements.
In the project: Template development takes place directly within the local FirstSpirit project instance.
In the file system: Theoretically, project content can also be edited directly in the file system.
However, external editing does result in limitations.
Furthermore, all data edited externally must be imported into the local project instance to make sure the external changes are consistent.
For further information, see Modification.
|
Notes on conflict handling: If multiple developers are editing elements at the same time, conflicts may occur when importing data into the project and these conflicts may not be detected at VCS level (e.g., namespace conflicts in FirstSpirit). Potential conflicts and solution strategies are described under Conflict handling. |
4) Export
From the FirstSpirit project to the file system (via External Synchronization)
Once a stable state has been achieved following completion of work on a work package, the developer exports his current development state using FSDevTools (fs-cli export). During this process, the development state from the local FirstSpirit project instance is exported into the target folder in the file system. Objects are created, updated, moved, and deleted within the file system.
This step is needed to transfer any modified content into the central development state.
For further information, see Export.
5) Commit / Push
From the file system to the repository (via VCS)
To start with, the development state from the target folder in the local system is confirmed in the local repository (e.g., in Git via “commit”).
Changes are then sent out of the local repository to the central repository (e.g., in Git using “push”). The changes made by all developers involved are merged at this level (“merge”). During this process, conflicts are automatically rectified and changes are versioned.
For further information, see Commit / Push.
Comments
Information about the scenarios described
The scenarios described are geared explicitly towards a distributed development model, i.e.:
- Multiple developers are involved.
- Each developer is using his own workstation with a local FirstSpirit Server.
- The FirstSpirit project data being edited by the developers are managed on each local FirstSpirit Server in a project “DevProject”
- The data in the FirstSpirit project “DevProject” are versioned using Git repository and synchronized between the developers’ workstations
- The Git repository already exists and can be accessed under the URL ssh://firstspirit.example/externalsync
- The Git repository is cloned in the D:\Git\DevProject directory on every workstation
The scenarios use the FSDevTools command line tool (fs-cli) and the command-line-based Git client (git).
|
The workflow and its individual steps may differ if you use other tools to use External Synchronization and/or to version the project data. |
Information about documentation
As the FirstSpirit development process is not the same in all companies and there are different ways of working with External Synchronization, this document describes best practice. This means that recommendations are provided on how External Synchronization can be best used. Other or new recommendations may arise as a result of experience with External Synchronization gathered in real projects by customers and partners.