Name: cirrus
Owner: Cloudant
Description: python library build, test and devop like things assistant
Forked from: evansde77/cirrus
Created: 2017-09-04 10:58:22.0
Updated: 2018-04-12 16:57:22.0
Pushed: 2018-04-12 16:57:20.0
Homepage: null
Size: 3644
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
python library build, test and devop like things assistant
All new development work on this fork should be based from the new-development
branch.
This repo was forked from evansde77/cirrus (a former Cloudant employee), but the forked version broke some Cloudant-specific tools.
Our solution was to check out the most recently working version, 0.1.7
and create a new release from that.
new-development
was also created from 0.1.7
, and this should be considerd the new develop
branch.1.0.0
was created from new-development
. -O https://raw.githubusercontent.com/cloudant/cirrus/new-development/installer.sh
installer.sh
The installer script will set up an install of cirrus for you in your home directory and prompt for some info so that it can set up some parameters in your .gitconfig The installer will create a virtualenv and install cirrus from pip via the cirrus-cli package, installing the latest available version.
Note: This package uses GitFlow, any development work should be done off the develop branches and pull requests made against develop, not master.
clone https://github.com/evansde77/cirrus.git
irrus
cirrus build
As cirrus works as a git extension, it will use your gitconfig file. The installer will create a cirrus section in this file and create the following settings:
Protip: If you require a different username for ssh access to your pypi server, you can add an optional pypi-ssh-user setting.
The per package controls used by cirrus live in a cirrus.conf file in the top level of the repo you use with cirrus. This file, coupled with the cirrus setup.py template and command line tools dictate the behaviour of the cirrus commands within the package. Details for the cirrus config are in the (TBA) Configuration.MD file
A simple test command that says hello, verifies that things are working and prints out some info about your cirrus install
Usage:
cirrus hello
Beta: new in Release 1.6 and above
The cirrus package command provides support for setting up cirrus to work in a new package. Assuming a starting point of a git repo with at least one commit on the master branch, you can run the git cirrus package init command to add the various configuration and packaging files used by cirrus. This is intended to provide a minimal working template, so some configuration post init will be needed to take advantage of other features.
The init command will do the following:
For example:
eate a minimal repo
r
est_repo/
init
checkout -b develop
r src
r throwaway
r src/throwaway
"__version__ = '0.0.0'\n" > src/throwaway/__init__.py
"requests\n" > requirements.txt
add src/throwaway/__init__.py requirements.txt
commit -m "make a package"
checkout master
merge develop
n the package init command
cirrus package init -p test_repo --no-remote -v 0.0.0 -s src --version-file=src/throwaway/__init__.py
n now use cirrus in the package, eg build:
cirrus build
Options available for the package init command:
Builds a new virtualenv and installs the requirements for the package, setting up a development/testing/deployment environment for the package.
Usage:
cirrus build
The virtualenv is created in ./venv. Optional parameters for the build command are read from the cirrus.conf, they are;
-c, --clean
removes the existing ./venv before building.-d, --docs
generate documentation using Sphinx and its generated Makefile. Any optional make commands can be passed along (e.g., –docs clean singlehtml)sphinx_makefile_dir
value set in the docs
section of cirrus.conf.sphinx_makefile_dir
should point to the directory that contains Sphinx's Makefile.Commands related to the creatation and management of a git-flow style feature branch.
Usage:
cirrus feature new BRANCH_NAME --push
cirrus feature pull-request --title TITLE --body BODY --notify @AGITHUBUSER,@ANOTHERGITHUBUSER
The cirrus review command provides some utilities for dealing with GitHub pull requests from the cirrus command line. Available commands are:
Examples:
cirrus review list --user evansde77 # list open PRs by user evansde77
cirrus review list # list all open PRs
cirrus review plusone --id 500 -c "+1" # adds the +1 context to the feature via a status update and sets it to success
cirrus review reviee --id 500 -m "great work, LGTM" --plus-one -c "+1" # adds a comment to the PR and sets the +1 context status to success
Commands related to creation of a new git-flow style release branch, building the release and uploading it to a pypi server. There are three subcommands:
Usage:
cirrus test # Stop if things are broken
cirrus release new --micro
cirrus release build
cirrus release merge --cleanup
cirrus release upload --plugin pypi
Options:
--bump foo==0.0.9 bar==1.2.3
.Release Options in cirrus.conf
You can customise the release merge workflow for each package via the cirrus config with the following settings:
Example:
ease]
_on_ci = False
_on_ci_develop = False
_on_ci_master = False
_on_ci_timeout = 600
_on_ci_interval = 2
ub_context_string = continuous-integration/travis-ci
te_github_context = True
_retry_attempts = 10
_retry_cooloff = 2
The release command works with two possible mode of [https://github.com/blog/2051-protected-branches-and-required-status-checks](GitHub branch protection) one in which you wait for the CI tests to run and update the status, and one in which there are no checks, so that you have to set status to merge branches in a git flow style.
For the waiting mode, simply flip the boolean wait_on_ci flag to True to wait on CI to run on the release branch. Likewise, the wait_on_ci_develop and wait_on_ci_master params will wait on CI status for the develop and master branches you have configured before merging. You can adjust the total timeout in seconds and the poll interval via the cirrus config file.
For the non-waiting mode, you provide the github context string you want to set and then when the merges back to develop and master occur, that state value is set to success. This mode of operation is useful when your CI system runs release tests in a way not connected to github, but you still have protected branches.
Protip: If you don't make releases regularly, you'll want to make sure your local repo copy is up to date (cirrus should do these eventually).
checkout master # get master, if you only have develop
fetch
fetch --tags
checkout develop # you're ready to release!
Protip: If something goes wrong during release building you may end up on a release/A.B.C branch that didn't work out. If you haven't pushed out the tag for the new version you can git checkout develop
and git branch -d release/A.B.C
. If you've pushed a bad version/tag the best thing to do is resolve the problem and create a new micro version – don't modify a tag that's already remote (consult your own release workflow).
Command for running tests in a package.
Usage:
cirrus test
Options and config: –suite SUITE_LOCATION
Must define name of virtualenv in [package] virtualenv Must define [test-default] where (default location for tests, optional if you choose to always include –suite) May define [test-SUITE_LOCATION] where
Command for running quality control checks via pylint, pyflakes, pep8.
Usage:
cirrus qc --files --only-changes --pylint --pyflakes --pep8
Options and config: Running with no arguments will run all checks on everything. To run only a specific checker (pylint, pyflakes, or pep8) use the corosponding argument or a combonation of them. Specific files may be ran using '–files' OR check only files that have not yet been commited to the repo by using the '–only-changes' argument. For pylint, a score threshold must be set in cirrus.conf [quality] threshold. The path to an optional rcfile (pylint configuration) may be set at [quality] rcfile.
The deploy command provides a plugin driven way to hook into deployment systems like chef and puppet. Since deployment is heavily customisable based on what system is in use, the command supports selecting a plugin and then delegates all CLI options to that plugin.
Usage:
cirrus deploy --plugin=<plugin_name> <options for plugin>
Deployer plugins live in cirrus.plugins.deployers and individual docs for each plugin can be found there.
Plugins:
Command for publishing Sphinx documentation
Usage:
cirrus docs build
cirrus docs pack
cirrus docs publish
Options and config:
git cirrus docs build
: --make <options>
--make
, the default options clean html
are usedsphinx_makefile_dir
value set in the doc
section of cirrus.conf.sphinx_makefile_dir
should point to the directory that contains Sphinx's Makefile.git cirrus docs pack
requires the following options in cirrus.conf [doc] section:git cirrus docs publish
requires the following options in cirrus.conf [doc] section:doc_file_server
plugin:put
command
Note: Optional if doc_file_server_sudo is Falsejenkins
plugin:Example cirrus.conf:
]
nx_makefile_dir = docs/
nx_doc_dir = docs/_build/html
fact_dir = docs/artifacts
isher = doc_file_server
_file_server]
file_server_url = http://localhost:8080
file_server_upload_path = /docs/package/archive
file_server_sudo = True
If using publisher = jenkins
:
kins]
= https://localhost:8080
job = doc_build
var = artifact
var = ARCHIVE
a_vars = True
kins_docs_extra_vars]
= value
= value1