The share repository, or simply “share”, is the central component to the Team Configuration functionality available as of the 5.2 release of Agentry. The share is the common project storage location of work performed by all developers for a single Agentry application project. When working with a share the Agentry project must be connected to that share. This then links the project with the share, tracking the changes made locally with the project as it exists in the share repository.
The basic requirements for a share repository are that it be stored in a location to which all developers on the team have read-write access to that location. Typically this is a common file server or equivalent that is accessible to all developers and is linked to each developer’s workstation as a mapped network drive in Windows. The directory in which the share is placed must exist prior to sharing the project. Multiple share repositories cannot be created in the same base directory. However, multiple shares can have a common ancestor directory.
As an example, a share can be created in the directory M:\SharedProjects\MobileNorthwindCRM. A second share can be created in the folder M:\SharedProjects\MobileNorthwindInventory. However, it is not allowed to create two shares in the directory M:\MobileNorthwindApps.
Each developer will perform operations related to the share that include reading from and writing to the share’s directory, and therefore each must have permissions to perform these operations on all files within the share location.
When a share is created (see “Creating a Share Repository” for details) a local project is first selected. A directory is then selected to store the share. Within this directory a file named share.ini is created containing information about the share. This file should never be manually modified unless directed by a Syclo support specialist. When checking out from a share to create a new local project based on that share’s tip revision, the share.ini file is selected as a part of that operation.
The initial revision in the share will then be the definitions in the selected local project. These items are written to the directory named 1. Subsequent commits to this share for developers create additional directories, each numbered to match the share revision created by that commit operation, e.g. 2, 3, 4.... As with the share.ini file, the contents of these sub-directories should never be modified manually unless under the specific direction of a Syclo support specialist.
The Share Project operation is the first step in creating a team environment for a common Agentry application project. This operation creates a share repository at a designated location. The new share contains a single, initial revision, i.e., revision 1. The contents of this revision match the contents of the local Agentry application project open within the Agentry Perspective when the share project operation is executed. This operation can only be executed on Agentry application projects not currently connected to a share repository.
The new share should be created in a location common to all developers on the team and according to the requirements of the share repository. The local project should be in a state in which it makes sense to share the project contents. This state will vary from one project to the next and depends on the division of work among the developers. The only requirements from a technical standpoint are that an Agentry application project exists within the Eclipse workspace and that project is open. No validation or check on publish is performed as a part of the share project operation. This means the project need not be in a publishable state prior to creating the share.
In practice, it is likely desirable that some useful functionality exist prior to creating the share. In many use cases the first revision of the share is the standard implementation of a product application, such as those provided by Syclo. For new application projects the functionality need not be nearly as robust, or even completely implemented before creating the share. Rather, the core pieces to the project, such as objects and their properties, fetches and pushes that may or may not yet contain step usage definitions, and screen sets with or without platforms or screens may all be a part of the initial revision of the share when created.
Typically when planning and creating a share, the developer responsible for creating these core definitions should perform their initial work (though it need not be the final planned result) and then create the share from their local project. This developer, as well as the rest of the team, can continue to work with the definitions once the share is created.
Once a share is created, other developers can access its contents for their own portion of the work for the project. To begin this work the developers will each need to check out the tip revision of the share repository. This is performed via the Import operation. During this operation the import wizard is displayed, the first screen of which provides the developer with the list of choices for the import source. One of these options is Agentry Share | Checkout Project from an Agentry Share (share.ini). Selecting this option indicates a new project is to be created in the local Eclipse workspace by checking out the tip revision from the share repository.
Once the share is selected as the source of the import, and other information is provided, the import operation creates a new Agentry application project within the workspace by importing the definitions within the share’s tip revision. When the operation is complete, the developer can modify and extend this project for their portion of the overall implementation. Typically a checkout is performed only once to create the local project. After this point, the developer performs commit operations to commit changes made to the local project to the share; and update operations to retrieve changes committed to the share by other developers.
When working with a project connected to a share, the developers on a team must perform the commit operation to commit changes made in their local projects to the share repository. A commit operation results in the addition of a new revision to the share. This new share then becomes the tip share that other developers receive when performing updates until a subsequent commit is performed by any developer connected to the share.
During the commit operation, the wizard screens displayed include a comments field. Within this field comments are automatically added to note all changes made to the local project. The comments reflect the type of change made, which can be add, edit, or delete, and the definition modified. These default comments can be edited prior to performing the actual commit. The final contents of this comment field are then the comments for the revision created by the commit, and will be viewable by all developers in the History View.
When performing a commit, the Agentry Editor first checks the local project for changes as compared to the share’s tip revision. If no changes exist, the commit will not be performed. The commit wizard’s OK button is disabled. The summary view within this wizard indicates no differences exist between the local project and current tip revision.
Another of the share operations is revert. Using this operation it is possible to revert the local project to a share revision earlier than the tip revision. When the local project is reverted to a previous revision and subsequent changes are made to the local project, a commit operation will display a warning message indicating the difference in revisions. Note that the current state of the local project will be committed to the share as the new tip revision. Any changes made and committed to the share between the reverted revision and the current tip revision will be lost when the new tip revision is committed. For this reason, reverting to a previous revision and then committing should only be performed in rare circumstances.
The update operation is performed by the developer to update the local Agentry application project to the tip revision of the share repository. This allows the developer to retrieve changes made by other developers working on the same project. During an update a check is first made for differences between the share revision and the local project. If changes exist for the same definition in both the local and share projects, a conflict exists. This requires manual resolution by the developer. The specific behavior of the update and the resolution depend on the nature of the conflict. When a conflict does occur, and there are other definitions in the share that should be imported that are not in conflict with the local project, those definitions are updated to the local project, leaving only the conflicted definitions in need of resolution. See the information on “Update Conflict Resolution” for details.
The Revert Operation for a share repository replaces the local project with the specified share revision. This revision can include the tip revision when the local project is at an earlier revision. The difference between a revision and an update is the, first, a specific revision can be selected, and, second, there is no conflict detection performed. This last revert behavior is important to note as it means that any uncommitted changes made to the local project are lost when the revert operation completes. One use for the revert operation can be to remove unwanted changes from the local project.
Note that while the tip revision can be selected in a revert operation it should never be used in place of the update operation. Reverting to the tip revision should only be performed when it is desired to remove all local changes. In such situations the developer should be careful to verify all local changes should be removed before proceeding.
The Show History operation does not affect either the local Agentry application project or the share repository. This operation opens the History View within which each repository revision is listed. The revision of the repository from which the last update to the local project was performed is highlighted.
Within this view the revision number, the date it was created, the user that created it, and the revision description as entered during the commit operation are listed. This is a read-only view intended to provide information about the local project as it relates to the share, as well as information about the share itself. This view can be refreshed at any time and will display any new revisions added to the share since the last refresh.
The history view should be reviewed prior to performing commit or update operations to understand the current state of the share before changes are made to it or the local project.
The Disconnect Operation disconnects the local Agentry project from the share repository. Once a project is disconnected it is no longer tied in any way to the share. Subsequent changes to the local project are made out of synch with the share. Such changes are not privately tagged by default.
This is only one scenario for disconnecting a project from a share. Others may exist, and the operation can be performed to meet any needs found by the developer.