Helix Swarm Guide (2019.1)

What’s new

This section provides a summary of the notable changes in Swarm for the 2019.1 release. Full details are available in the distribution's RELNOTES.txt file.

Important information

Custom module support in Swarm 2019.1

We have upgraded the version of Zend framework used in Swarm 2019.1 to Zend 3. If you have any custom Swarm modules they will need to be updated to work in Swarm 2019.1. For instructions on updating custom modules for the Zend 3 framework, see Upgrade custom modules to work with Zend 3.

PHP and Apache version support changed for Swarm version 2019.1

We have removed support for versions of PHP older than 7.0 in Swarm 2019.1. As a result of this change, support for Apache 2.2 has also been removed. This is part of our commitment to move away from using versions of platforms that have reached End-of-Life (EOL).
Ensure that you can install a supported version of PHP and Apache before upgrading to Swarm 2019.1. For information on versions of PHP and Apache supported by Swarm, see PHP and Apache web server.

P4PHP 2019.1 or later required for Swarm 2019.1 and later

The latest version of P4PHP is included in the Swarm package, OVA, and tarball installations.

New trigger scripts added for Swarm 2018.2

The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines were added in Swarm 2018.2, these are a prerequisite for the new Swarm Workflow technology preview feature.
If the Workflow feature is enabled, the trigger lines must be added to the Helix Server trigger table. Any earlier enforce and strict triggers must be commented out, see setup the trigger table.

New trigger script added for Swarm 2018.1

A new trigger script called swarm.shelvedel shelve-del has been added, this is a prerequisite for the new process_shelf_delete_when configurable. The trigger script must be added to the Helix Server trigger table.
Swarm checks for a supported Helix Server version when you install or upgrade Swarm. If a supported version of Helix Server is not found the swarm.shelvedel shelve-delete trigger and process_shelf_delete_when configurable are not supported, see Helix Server requirements.

Upgrade process changed

The upgrade process changed for Swarm version 2017.3 and later.

  • If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on Dashboard, and Reviews list pages. See Upgrading Swarm for details.
  • Note

    If you are upgrading from Swarm version 2017.3 or later, the index upgrade step is not required.

New functionality

Markdown support improved
  • Swarm now supports a number of Markdown file extensions. Valid Markdown file extensions are: md, markdown, mdown, mkdn, mkd, mdwn, mdtxt, mdtext.
  • The Files section now displays rendered Markdown text in a new Markdown tab, the View tab is still present and displays plain text as before, see Markdown files.
  • You can now use more Markdown styles in comments, see Markdown.
  • Administrators can now restrict what is rendered in Markdown in project overview pages and files for added security, see Markdown.
Swarm upgraded to use the Zend 3 framework
Swarm now uses the Zend 3 framework, this is part of our commitment to move away from using versions of platforms that have reached End-of-Life (EOL). For instructions on updating custom modules for the Zend 3 framework, see Upgrade custom modules to work with Zend 3.
Review page improved
  • Swarm now displays the revision of the review being viewed and the total number of revisions available in brackets next to the Review ID on the Review page.
  • When continuous integration has been configured for a project, a new Tests in Progress Tests in Progress image state has been added to the existing Tests Passed Tests Passed image and Tests Failed Tests Failed image states displayed on the Review page.

Technology preview features

Warning

Technology preview features:

Technology Preview features are currently unsupported, might not be functionally complete, and are not suitable for deployment in production. Technology preview features are subject to change and may be removed before they become fully supported features.

These features are provided to the customer to solicit interest and feedback, with the goal of full support in future releases. Customers are encouraged to provide feedback and functionality suggestions for Technology Preview features before they become fully supported.

Workflow

Workflow is a technology preview feature and is disabled by default.

Workflow rules
Swarm users can now create and manage workflows to ensure that changelists and code reviews in a project/branch follow the rules specified in that workflow. See Workflow overview.
A workflow is made up of a combination of the following rules (see Workflow rules for full details):
On commit without review: determine what happens when a changelist is committed without a review. Allow the commit, automatically create a review, or reject the commit.
On commit with a review: determine what happens when a changelist is committed with a review. Allow the commit or reject the commit unless the review is approved.
On update of a review in an end state: stop a review from being changed if it is in a review state that is considered complete. The review states that are considered complete are set by the administrator. Allow the review to be changed, or reject the change.
Count up votes from: define whose up votes count towards the Minimum up votes value set on the project/branch the review is associated with. All up votes count or only project member up votes count.
Automatically approve reviews: enable automatic approval of a review when all of its voting requirements are satisfied. Never automatically approve a review or automatically approve review.
Global workflow rules
Swarm administrators can now enforce individual workflow rules on projects/branches without an associated workflow or enforce a minimum workflow on the entire Helix Core Server. For more information about global workflow rules, see Workflow global rules - Technology preview feature.
New Workflow trigger scripts added in Swarm 2018.2
The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines were added in Swarm 2018.2, these are a prerequisite for the new Swarm workflow rules.
If the Workflow feature is enabled, the trigger lines must be added to the Helix Server trigger table. Any earlier enforce and strict triggers must be commented out, see setup the trigger table.

Workflow caveats

Possible performance issues on large Swarm systems
The Workflow technology preview feature has not been fully optimized and tested on Swarm systems with a large number of projects, branches, and paths.
Workflow trigger scripts have different functionality to the previous strict and enforce triggers
Trigger types checkenforced, checkstrict, and checkshelve were introduced in Swarm 2018.2 for the Workflow technology preview feature. The workflow triggers do not support the following trigger functionality available in Swarm 2018.1 and earlier:
  • -g group: Specifies a group to exclude from enforce or strict verifications. Members of the group (including sub-groups) are not subject to enforce or strict verifications.
  • EXEMPT_FILE_COUNT: When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.
  • EXEMPT_EXTENSIONS: A comma separated list of file extension. Commits with files having only these extensions are exempt from enforce or strict verifications.
To continue to use this functionality, you must keep your existing enforce and strict triggers and leave the Workflow technology feature disabled.

Known limitations

Swarm support for the "Private editing of streams" feature in Helix Server 2019.1
Supported: stream specs can be edited in your workspace using the Private editing of streams feature.
Not supported: if you request a review from a changelist that contains a stream spec that was edited using this feature it will not be displayed in the review. Other files in the changelist are displayed correctly in the review.
Fix: Swarm support for displaying these privately edited stream specs in reviews is on the current Swarm road map.
Multiple-Helix Server instances on a single Swarm instance

Issue: Swarm will lose connection to all of the Helix Servers if you edit the base_url configurable value in the environment block of <swarm_root>/data/config.php. This will stop your system working.

Fix: Remove the base_url configurable from the environment block of <swarm_root>/data/config.php.

Global Dashboard does not support MFA login
Issue: You cannot login into server instances from the global dashboard if you have MFA enabled on Swarm.
Workaround: Log in to each instance individually by including the server instance name in the URL, for example: https://swarm.company.com/serverA.
Project Commits tab can fail to show some Helix Server commits in the top level view
The Project Commits tab top level client view is made up of all of the branches of the project.
 
For example, Project Alpha:
 
Branch: QA:
//depot/alpha/dev/QA/...
 
Branch: Dev :
//depot/alpha/dev/...
-//depot/alpha/dev/QA/...
 
The project commits tab view is generated by processing the branches in the order that they were created in and from top to bottom for the paths in each of those branches.
For the project Alpha example above:
The first path includes all of the directories and files under //depot/alpha/dev/QA/ in the project commits tab top level view.
The second path includes all of the directories and files under //depot/alpha/dev/ in the project commits tab top level view.
The third path excludes all of the directories and files in //depot/alpha/dev/QA/ from the project commits tab top level view.
 
Result: commits made to //depot/alpha/dev/QA/ that should be shown for the QA branch are not displayed in the Project Commits tab top level view.
 
When you have a simple branch structure this can be avoided by considering this issue when you create your branches. In the example above, creating the Dev branch first and then creating the QA branch avoids the problem because//depot/alpha/dev/QA/ is not excluded from the Project Commits tab top level view.
Tip

Individual branch views display the commits correctly.

Zip file does not include files marked for Add
Files Marked for Add in pre-commit reviews and shelved changelists are not included in the zip file.
Swarm OVA installation fails with a Run p4 login2 error
Issue: Swarm OVA deployment against an MFA enabled Helix Server fails with a Run p4 login2 error.
Workaround: You must run p4 login2 for a super user account that has MFA enabled before deploying the Swarm OVA. For p4 login2 detail, see p4 login2 in P4 Command Reference.
Task Stream Reviews
Pre-commit reviews in a task stream are not yet supported.