jjb/jenkins-job-builder
Code Issues Proposed changes

Reformat docstrings for SCM

Browse Source 
Tidy up the docstrings to use consistent formatting, move inline
examples to tests and add urls for additional information on source code
web browsers.

Change-Id: I696389516dbd4e0960986666e32fab93e515710e
This commit is contained in:
Darragh Bailey 2015-07-10 15:53:24 +01:00 committed by Khai Do
parent 19aed6592f
commit 39df8466fd
7 changed files with 203 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

303
jenkins_jobs/modules/scm.py
View File

@ -50,23 +50,25 @@ def git(parser, xml_parent, data):
:arg str url: URL of the git repository
:arg str credentials-id: ID of credential to use to connect, which is the
last field(a 32-digit hexadecimal code) of the path of URL visible after
you clicked the credential under Jenkins Global credentials. (optional)
:arg str refspec: refspec to fetch (default '+refs/heads/\*:refs/remotes/\
remoteName/\*')
last field (a 32-digit hexadecimal code) of the path of URL visible
after you clicked the credential under Jenkins Global credentials.
(optional)
:arg str refspec: refspec to fetch (default
'+refs/heads/\*:refs/remotes/remoteName/\*')
:arg str name: name to fetch (default 'origin')
:arg list(str) remotes: list of remotes to set up (optional, only needed if
multiple remotes need to be set up)
multiple remotes need to be set up)
:Remote: * **url** (`string`) - url of remote repo
* **refspec** (`string`) - refspec to fetch (optional)
* **credentials-id** - ID of credential to use to connect,
which is the last field of the path of URL
(a 32-digit hexadecimal code) visible after you clicked
credential under Jenkins Global credentials. (optional)
:Remote:
* **url** (`string`) - url of remote repo
* **refspec** (`string`) - refspec to fetch (optional)
* **credentials-id** - ID of credential to use to connect, which
is the last field of the path of URL (a 32-digit hexadecimal
code) visible after you clicked credential under Jenkins Global
credentials. (optional)
:arg list(str) branches: list of branch specifiers to build (default '**')
:arg list(str) excluded-users: list of users to ignore revisions from
when polling for changes. (if polling is enabled, optional)
when polling for changes. (if polling is enabled, optional)
:arg list(str) included-regions: list of file/folders to include (optional)
:arg list(str) excluded-regions: list of file/folders to exclude (optional)
:arg str local-branch: Checkout/merge to local branch (optional)
@ -81,7 +83,7 @@ remoteName/\*')
* **fast-forward-mode** (`string`) - merge fast-forward mode.
Can be one of 'FF', 'FF_ONLY' or 'NO_FF'. (default 'FF')
:arg str basedir: location relative to the workspace root to clone to
(default: workspace)
(default workspace)
:arg bool skip-tag: Skip tagging (default false)
:arg bool shallow-clone: Perform shallow clone (default false)
:arg bool prune: Prune remote branches (default false)
@ -100,98 +102,86 @@ remoteName/\*')
.. deprecated:: 1.1.1. Please use submodule extension.
:arg bool use-author: Use author rather than committer in Jenkin's build
changeset (default false)
changeset (default false)
:arg str git-tool: The name of the Git installation to use (default
'Default')
'Default')
:arg str reference-repo: Path of the reference repo to use during clone
(optional)
(optional)
:arg str scm-name: The unique scm name for this Git SCM (optional)
:arg bool ignore-notify: Ignore notifyCommit URL accesses (default false)
:arg str browser: what repository browser to use (default '(Auto)')
:arg str browser: what repository browser to use.
:browsers supported:
* **auto** - (default)
* **assemblaweb** - https://www.assembla.com/
* **bitbucketweb** - https://www.bitbucket.org/
* **cgit** - http://git.zx2c4.com/cgit/about/
* **fisheye** - https://www.atlassian.com/software/fisheye
* **gitblit** - http://gitblit.com/
* **githubweb** - https://github.com/
* **gitiles** - https://code.google.com/p/gitiles/
* **gitlab** - https://about.gitlab.com/
* **gitlist** - http://gitlist.org/
* **gitoriousweb** - https://gitorious.org/
* **gitweb** - http://git-scm.com/docs/gitweb
* **kiln** - https://www.fogcreek.com/kiln/
* **microsoft\-tfs\-2013** - |tfs_2013|
* **phabricator** - http://phabricator.org/
* **redmineweb** - http://www.redmine.org/
* **rhodecode** - https://rhodecode.com/
* **stash** - https://www.atlassian.com/software/stash
* **viewgit** - http://viewgit.fealdia.org/
:arg str browser-url: url for the repository browser (required if browser
is not '(Auto)', no default)
is not 'auto', no default)
:arg str browser-version: version of the repository browser (GitLab only,
default '0.0')
default '0.0')
:arg str project-name: project name in Gitblit and ViewGit repobrowser
(optional)
(optional)
:arg str repo-name: repository name in phabricator repobrowser (optional)
:arg str choosing-strategy: Jenkins class for selecting what to build
(default 'default')
:arg str choosing-strategy: Jenkins class for selecting what to build.
Can be one of `default`, `inverse`, or `gerrit` (default 'default')
:arg str git-config-name: Configure name for Git clone (optional)
:arg str git-config-email: Configure email for Git clone (optional)
:extensions:
:arg dict changelog-against:
:changelog-against:
* **remote** (`string`) - name of repo that contains branch to
create changelog against (default 'origin')
* **branch** (`string`) - name of the branch to create
changelog against (default 'master')
:arg dict clean:
:clean:
* **after** (`bool`) - Clean the workspace after checkout
* **before** (`bool`) - Clean the workspace before checkout
* **changelog-against** (`dict`)
* **remote** (`string`) - name of repo that contains branch to
create changelog against (default 'origin')
* **branch** (`string`) - name of the branch to create changelog
against (default 'master')
* **clean** (`dict`)
* **after** (`bool`) - Clean the workspace after checkout
* **before** (`bool`) - Clean the workspace before checkout
* **ignore-commits-with-messages** (`list(str)`) - Revisions committed
with messages matching these patterns will be ignored. (optional)
* **force-polling-using-workspace** (`bool`) - Force polling using
workspace (default false)
* **sparse-checkout** (`dict`)
* **paths** (`list`) - List of paths to sparse checkout. (optional)
* **submodule** (`dict`)
* **disable** (`bool`) - By disabling support for submodules you
can still keep using basic git plugin functionality and just have
Jenkins to ignore submodules completely as if they didn't exist.
* **recursive** (`bool`) - Retrieve all submodules recursively
(uses '--recursive' option which requires git>=1.6.5)
* **tracking** (`bool`) - Retrieve the tip of the configured
branch in .gitmodules (Uses '\-\-remote' option which requires
git>=1.8.2)
* **timeout** (`int`) - Specify a timeout (in minutes) for
submodules operations (default: 10).
* **timeout** (`str`) - Timeout for git commands in minutes (optional)
* **wipe-workspace** (`bool`) - Wipe out workspace before build
(default true)
:arg list(str) ignore-commits-with-messages: Revisions committed with
messages matching these patterns will be ignored. (optional)
:arg bool force-polling-using-workspace: Force polling using workspace
(default false)
:arg dict sparse-checkout:
:sparse-checkout:
* **paths** (`list`) - List of paths to sparse checkout.
(optional)
:arg dict submodule:
:submodule:
* **disable** (`bool`) - By disabling support for submodules
you can still keep using basic git plugin functionality
and just have Jenkins to ignore submodules completely as
if they didn't exist.
* **recursive** (`bool`) - Retrieve all submodules recursively
(uses '--recursive' option which requires git>=1.6.5)
* **tracking** (`bool`) - Retrieve the tip of the configured
branch in .gitmodules (Uses '--remote' option which
requires git>=1.8.2)
* **timeout** (`int`) - Specify a timeout (in minutes) for
submodules operations (default: 10).
:arg str timeout: Timeout for git commands in minutes (optional)
:arg bool wipe-workspace: Wipe out workspace before build
(default true)
:browser values:
:auto:
:assemblaweb:
:bitbucketweb:
:cgit:
:fisheye:
:gitblit:
:githubweb:
:gitiles:
:gitlab:
:gitlist:
:gitoriousweb:
:gitweb:
:kiln:
:microsoft-tfs-2013:
:phabricator:
:redmineweb:
:rhodecode:
:stash:
:viewgit:
:choosing-strategy values:
:default:
:inverse:
:gerrit:
Example:
.. literalinclude:: /../../tests/scm/fixtures/git001.yaml
.. |tfs_2013| replace::
https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx
"""
logger = logging.getLogger("%s:git" % __name__)
@ -441,21 +431,21 @@ def repo(parser, xml_parent, data):
:arg str manifest-url: URL of the repo manifest
:arg str manifest-branch: The branch of the manifest to use (optional)
:arg str manifest-file: Initial manifest file to use when initialising
(optional)
(optional)
:arg str manifest-group: Only retrieve those projects in the manifest
tagged with the provided group name (optional)
tagged with the provided group name (optional)
:arg str destination-dir: Location relative to the workspace root to clone
under (optional)
under (optional)
:arg str repo-url: custom url to retrieve the repo application (optional)
:arg str mirror-dir: Path to mirror directory to reference when
initialising (optional)
initialising (optional)
:arg int jobs: Number of projects to fetch simultaneously (default 0)
:arg bool current-branch: Fetch only the current branch from the server
(default true)
(default true)
:arg bool quiet: Make repo more quiet
(default true)
(default true)
:arg str local-manifest: Contents of .repo/local_manifest.xml, written
prior to calling sync (optional)
prior to calling sync (optional)
Example:
@ -507,11 +497,11 @@ def store(parser, xml_parent, data):
:arg str script: name of the Store script to run
:arg str repository: name of the Store repository
:arg str version-regex: regular expression that specifies which pundle
versions should be considered (optional)
versions should be considered (optional)
:arg str minimum-blessing: minimum blessing level to consider (optional)
:arg str parcel-builder-file: name of the file to generate as input to
a later parcel building step (optional - if not specified, then
no parcel builder file will be generated)
a later parcel building step (optional - if not specified, then no
parcel builder file will be generated)
:arg list pundles:
:(package or bundle): (`dict`): A package or bundle to check
@ -566,44 +556,46 @@ def svn(parser, xml_parent, data):
:arg str url: URL of the svn repository
:arg str basedir: location relative to the workspace root to checkout to
(default '.')
(default '.')
:arg str credentials-id: optional argument to specify the ID of credentials
to use
to use
:arg str repo-depth: Repository depth. Can be one of 'infinity', 'empty',
'files', 'immediates' or 'unknown'. (default 'infinity')
'files', 'immediates' or 'unknown'. (default 'infinity')
:arg bool ignore-externals: Ignore Externals. (default false)
:arg str workspaceupdater: optional argument to specify
how to update the workspace (default wipeworkspace)
:arg str workspaceupdater: optional argument to specify how to update the
workspace (default wipeworkspace)
:supported values:
* **wipeworkspace** - deletes the workspace before checking out
* **revertupdate** - do an svn revert then an svn update
* **emulateclean** - delete unversioned/ignored files then update
* **update** - do an svn update as much as possible
:arg list(str) excluded-users: list of users to ignore revisions from
when polling for changes (if polling is enabled; parameter is optional)
when polling for changes (if polling is enabled; parameter is optional)
:arg list(str) included-regions: list of file/folders to include
(optional)
(optional)
:arg list(str) excluded-regions: list of file/folders to exclude (optional)
:arg list(str) excluded-commit-messages: list of commit messages to exclude
(optional)
(optional)
:arg str exclusion-revprop-name: revision svn-property to ignore (optional)
:arg bool ignore-property-changes-on-directories: ignore svn-property only
changes of directories (default false)
changes of directories (default false)
:arg bool filter-changelog: If set Jenkins will apply the same inclusion
and exclusion patterns for displaying changelog entries as it does for
polling for changes (default false)
and exclusion patterns for displaying changelog entries as it does for
polling for changes (default false)
:arg list repos: list of repositories to checkout (optional)
:arg str viewvc-url: URL of the svn web interface (optional)
:Repo: * **url** (`str`) -- URL for the repository
* **basedir** (`str`) -- Location relative to the workspace
root to checkout to (default '.')
* **credentials-id** - optional ID of credentials to use
* **repo-depth** - Repository depth. Can be one of 'infinity',
'empty', 'files', 'immediates' or 'unknown'.
(default 'infinity')
* **ignore-externals** - Ignore Externals. (default false)
:workspaceupdater values:
:wipeworkspace: - deletes the workspace before checking out
:revertupdate: - do an svn revert then an svn update
:emulateclean: - delete unversioned/ignored files then update
:update: - do an svn update as much as possible
:Repo:
* **url** (`str`) -- URL for the repository
* **basedir** (`str`) -- Location relative to the workspace root
to checkout to (default '.')
* **credentials-id** - optional ID of credentials to use
* **repo-depth** - Repository depth. Can be one of 'infinity',
'empty', 'files', 'immediates' or 'unknown'. (default 'infinity')
* **ignore-externals** - Ignore Externals. (default false)
Multiple repos example:
@ -743,37 +735,11 @@ def tfs(parser, xml_parent, data):
uses server-url)
Examples::
Examples:
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:
- web-url: "http://TFSMachine:8080"
.. literalinclude:: /../../tests/scm/fixtures/tfs-001.yaml
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "jane@mydomain"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
.. literalinclude:: /../../tests/scm/fixtures/tfs-002.yaml
"""
@ -856,28 +822,31 @@ def hg(self, xml_parent, data):
:arg str credentials-id: ID of credentials to use to connect (optional)
:arg str revision-type: revision type to use (default 'branch')
:arg str revision: the branch or tag name you would like to track
(default 'default')
(default 'default')
:arg list(str) modules: reduce unnecessary builds by specifying a list of
"modules" within the repository. A module is a directory name within the
repository that this project lives in. (default '')
"modules" within the repository. A module is a directory name within
the repository that this project lives in. (default '')
:arg bool clean: wipe any local modifications or untracked files in the
repository checkout (default false)
repository checkout (default false)
:arg str subdir: check out the Mercurial repository into this
subdirectory of the job's workspace (optional)
subdirectory of the job's workspace (optional)
:arg bool disable-changelog: do not calculate the Mercurial changelog
for each build (default false)
:arg str browser: what repository browser to use (default 'auto')
:arg str browser-url: url for the repository browser
(required if browser is set)
for each build (default false)
:arg str browser: what repository browser to use
:browsers supported:
* **auto** - (default)
* **bitbucketweb** - https://www.bitbucket.org/
* **fisheye** - https://www.atlassian.com/software/fisheye
* **googlecode** - https://code.google.com/
* **hgweb** - https://www.selenic.com/hg/help/hgweb
* **kilnhg** - https://www.fogcreek.com/kiln/
* **rhodecode** - https://rhodecode.com/ (versions >= 1.2)
* **rhodecode-pre-1.2.0** - https://rhodecode.com/ (versions < 1.2)
:arg str browser-url: url for the repository browser
(required if browser is set)
:browser values:
:fisheye:
:bitbucketweb:
:googlecode:
:hgweb:
:kilnhg:
:rhodecode:
:rhodecodelegacy:
Example:

15
tests/scm/fixtures/tfs-001.xml Normal file
View File

@ -0,0 +1,15 @@
<?xml version="1.0" encoding="utf-8"?>
<project>
<scm class="hudson.plugins.tfs.TeamFoundationServerScm">
<serverUrl>tfs.company.com</serverUrl>
<projectPath>$/myproject</projectPath>
<localPath>../foo/</localPath>
<workspaceName>Hudson-${JOB_NAME}</workspaceName>
<userPassword/>
<userName>mydomain\\jane</userName>
<useUpdate>False</useUpdate>
<repositoryBrowser class="hudson.plugins.tfs.browsers.TeamSystemWebAccessBrowser">
<url>http://TFSMachine:8080</url>
</repositoryBrowser>
</scm>
</project>

10
tests/scm/fixtures/tfs-001.yaml Normal file
View File

@ -0,0 +1,10 @@
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:
- web-url: "http://TFSMachine:8080"

13
tests/scm/fixtures/tfs-002.xml Normal file
View File

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="utf-8"?>
<project>
<scm class="hudson.plugins.tfs.TeamFoundationServerScm">
<serverUrl>tfs.company.com</serverUrl>
<projectPath>$/myproject</projectPath>
<localPath>../foo/</localPath>
<workspaceName>Hudson-${JOB_NAME}</workspaceName>
<userPassword/>
<userName>jane@mydomain</userName>
<useUpdate>False</useUpdate>
<repositoryBrowser class="hudson.plugins.tfs.browsers.TeamSystemWebAccessBrowser"/>
</scm>
</project>

9
tests/scm/fixtures/tfs-002.yaml Normal file
View File

@ -0,0 +1,9 @@
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "jane@mydomain"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"
web-access:

12
tests/scm/fixtures/tfs-003.xml Normal file
View File

@ -0,0 +1,12 @@
<?xml version="1.0" encoding="utf-8"?>
<project>
<scm class="hudson.plugins.tfs.TeamFoundationServerScm">
<serverUrl>tfs.company.com</serverUrl>
<projectPath>$/myproject</projectPath>
<localPath>../foo/</localPath>
<workspaceName>Hudson-${JOB_NAME}</workspaceName>
<userPassword/>
<userName>mydomain\\jane</userName>
<useUpdate>False</useUpdate>
</scm>
</project>

8
tests/scm/fixtures/tfs-003.yaml Normal file
View File

@ -0,0 +1,8 @@
scm:
- tfs:
server-url: "tfs.company.com"
project-path: "$/myproject"
login: "mydomain\\\\jane"
use-update: false
local-path: "../foo/"
workspace: "Hudson-${JOB_NAME}"