This is an implementation of Atlassian's Smart Commits concept for Perforce Swarm. Atlassian's documentation is here. This implementation is nearly identical to their spec. The general idea is that you can use commands in your changelist description to carry out actions on JIRA issues.
<?php
\Laminas\Loader\AutoloaderFactory::factory(
array(
'Laminas\Loader\StandardAutoloader' => array(
'namespaces' => array(
'JiraPerforceSmartCommits' => BASE_PATH . '/module/JiraPerforceSmartCommits/src',
)
)
)
);
return [
'JiraPerforceSmartCommits',
];
The following configurables are available for this module:
'jirasmartcommits' => array(
'host' => 'https://your-studio.atlassian.net',
'user' => 'username',
'password' => 'password',
'cite_submitter_username' => true,
'link_changelist_comment_reference' => true,
),
This block should be a peer of 'p4'
.
host
- URL for your installed JIRA web interface or cloud address (start with https:// or http://)user
- Jira Cloud: the username used to connect to your Atlassian account, Jira on-premises: the username required for Jira API accesspassword
- Jira Cloud: a special API token obtained from https://id.atlassian.com/manage/api-tokens, Jira on-premises: the password required for Jira API accesscite_submitter_username
- if Perforce and Jira have the same users, leave this option on to reference the submitter in any comment made.link_changelist_comment_reference
- whether to link the changelist number in a comment back to Swarm's changeVote on https://jira.atlassian.com/browse/JRASERVER-35124 to allow comments to be made on behalf of the submitter for on-premises installations.
On a single line in your changelist description, reference one or more JIRA issues then enter one or more commands. Valid commands are:
Commands must be on the same line as the JIRA issue key(s) they apply to. This is because multiple keys can have multiple actions taken on them in a single changelist description (see example below).
Commands must have a space before them. "Removed problematic condition#done" wouldn't work, for example.
Anything between the JIRA issue key and commands (or before a JIRA key) is ignored. So, for example, this changelist description:
[JRA-1234] - Enable Smart Commits for Perforce #done
would transition issue JRA-1234 to Done without any comment or time logging.
Work done toward JRA-1234, PERFORCE-1000. #comment Got basic framework up and running. #time 1d
This would log 1 day of work with the comment "Got basic framework up and running" on both JRA-1234 and PERFORCE-1000. Multiple issues can be separated by any text, not just commas or whitespace. Multiple issues can be handled separately if you wish:
JRA-1234 #done #comment Completed final outstanding work item. PERFORCE-1000 #comment Nearly done, just need to add handling for different types of transitions.
Basically all you need to do is reference one or more JIRA issues followed by one or more commands. It tries to intelligently handle text so you can separate changelist descriptions from JIRA comments (perhaps you want to go into more detail in Perforce than is necessary on JIRA, for example).
Until Atlassian provides a way for automation/service users to act on behalf of other users on JIRA server instances (https://jira.atlassian.com/browse/JRASERVER-35124), all commands will be performed by the user configured in the module. Comments will @reference the user that made the commit, if that option is enabled, but will still always come from the configured user.