README.rst
1README
2======
3
4Jenkins Job Builder takes simple descriptions of Jenkins_ jobs in YAML_ or JSON_
5format and uses them to configure Jenkins. You can keep your job descriptions in
6human readable text format in a version control system to make changes and
7auditing easier. It also has a flexible template system, so creating many
8similarly configured jobs is easy.
9
10To install::
11
12 $ pip install --user jenkins-job-builder
13
14Online documentation:
15
16* https://jenkins-job-builder.readthedocs.io/en/latest/
17
18Developers
19----------
20Bug report:
21
22* https://storyboard.openstack.org/#!/project/723
23
24Repository:
25
26* https://opendev.org/jjb/jenkins-job-builder
27
28Cloning::
29
30 git clone https://opendev.org/jjb/jenkins-job-builder.git
31
32Install pre-commit from https://pre-commit.com/#intro in order to run some
33minimal testing on your commits.
34
35A virtual environment is recommended for development. For example, Jenkins
36Job Builder may be installed from the top level directory::
37
38 $ virtualenv .venv
39 $ source .venv/bin/activate
40 $ pip install -r test-requirements.txt -e .
41
42Patches are submitted via Gerrit at:
43
44* https://review.opendev.org
45
46Please do not submit GitHub pull requests, they will be automatically closed.
47
48Mailing list:
49
50* https://groups.google.com/forum/#!forum/jenkins-job-builder
51
52IRC:
53
54* ``#openstack-jjb`` on OFTC
55
56More details on how you can contribute is available on our wiki at:
57
58* https://docs.openstack.org/infra/manual/developers.html
59
60Writing a patch
61---------------
62
63We ask that all code submissions be pep8_ and pyflakes_ clean. The
64easiest way to do that is to run tox_ before submitting code for
65review in Gerrit. It will run ``pep8`` and ``pyflakes`` in the same
66manner as the automated test suite that will run on proposed
67patchsets.
68
69When creating new YAML components, please observe the following style
70conventions:
71
72* All YAML identifiers (including component names and arguments)
73 should be lower-case and multiple word identifiers should use
74 hyphens. E.g., "build-trigger".
75* The Python functions that implement components should have the same
76 name as the YAML keyword, but should use underscores instead of
77 hyphens. E.g., "build_trigger".
78
79This consistency will help users avoid simple mistakes when writing
80YAML, as well as developers when matching YAML components to Python
81implementation.
82
83Unit Tests
84----------
85
86Unit tests have been included and are in the ``tests`` folder. Many unit
87tests samples are included as examples in our documentation to ensure that
88examples are kept current with existing behaviour. To run the unit tests,
89execute the command::
90
91 tox -e py34,py27
92
93* Note: View ``tox.ini`` to run tests on other versions of Python,
94 generating the documentation and additionally for any special notes
95 on running the test to validate documentation external URLs from behind
96 proxies.
97
98Installing without setup.py
99---------------------------
100
101For YAML support, you will need libyaml_ installed.
102
103Mac OS X::
104
105 $ brew install libyaml
106
107Then install the required python packages using pip_::
108
109 $ sudo pip install PyYAML python-jenkins
110
111.. _Jenkins: https://jenkins.io/
112.. _YAML: https://yaml.org
113.. _JSON: http://json.org/
114.. _pep8: https://pypi.org/project/pep8
115.. _pyflakes: https://pypi.org/project/pyflakes
116.. _tox: https://tox.readthedocs.io/en/latest
117.. _libyaml: https://pyyaml.org/wiki/LibYAML
118.. _pip: https://pypi.org/project/pip
119