Skip to content
This repository was archived by the owner on Oct 7, 2024. It is now read-only.

Commit cd3852e

Browse files
gaborbernatgaborbernat
committed
document template
1 parent 4950cd2 commit cd3852e

File tree

4 files changed

+152
-12
lines changed

4 files changed

+152
-12
lines changed

‎README.md‎

Lines changed: 138 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,139 @@
1-
# azure-pipelines-template
2-
template for your azure pipelines
1+
# tox azure-pipeline-template
32

3+
This a template that will help simplify the [Azure Pipelines](https://azure.microsoft.com/en-gb/services/devops/pipelines/)
4+
configuration when using [tox](https://tox.readthedocs.org) to drive your CI.
5+
6+
# usage
7+
8+
**First configure a github service connection**
9+
10+
It is suggested to use a generic name, such as `github` so forks can also configure the same.
11+
12+
You can find this in `Project Settings` => `Service connections` in the Azure Devops dashboard for your project.
13+
Project settings is located in the bottom left corner of the UI as of 2019-04-30. Below I'm using the endpoint name
14+
`github`.
15+
16+
**To load the template, add this to the beginning of the `azure-pipelines.yml`**
17+
18+
```yaml
19+
resources:
20+
repositories:
21+
- repository: tox
22+
type: github
23+
endpoint: github
24+
name: tox-dev/azure-pipelines-template
25+
ref: refs/tags/0.1
26+
```
27+
28+
this will make the templates in this repository available in the `tox` namespace.
29+
30+
# job templates
31+
32+
## `run-tox-env.yml`
33+
This job template will run tox for a given set of tox targets on given platform (new in `0.1`).
34+
Features and functionality:
35+
36+
- each specified toxenv target maps to a single Azure Pipelines job
37+
- provision a python for the job
38+
- install tox into that python
39+
- provision the target tox environment (create environment, install dependencies)
40+
- invoke the tox target
41+
- if a junit file is found under `.tox\junit.{toxenv}.xml` upload it as test report
42+
- if a coverage file is found under `.tox\coverage.xml` or `.tox\.coverage` upload it as build artifact
43+
44+
### example
45+
46+
The following example will run `py36` and `py37` on Windows, Linux and MacOs. It will also invoke
47+
`fix_lint` and `docs` target with `python3.7` on Linux. Note how the root level name can be used
48+
to automatically specify the target platform (defaults to Linux).
49+
50+
```yaml
51+
jobs:
52+
- template: run-tox-env.yml@tox
53+
parameters:
54+
jobs:
55+
windows:
56+
toxenvs:
57+
- py37
58+
- py36
59+
linux:
60+
toxenvs:
61+
- py37
62+
- py36
63+
macOs:
64+
toxenvs:
65+
- py37
66+
- py27
67+
check:
68+
py: '3.7'
69+
toxenvs:
70+
- fix_lint
71+
- docs
72+
```
73+
74+
75+
### parameters
76+
77+
At root level has a single ``jobs`` key. Inside this you can enlist groups of targets as maps.
78+
The key is the name of the group. The values configure the target:
79+
80+
- `toxenvs`: the list of `tox` environment names to run; must either:
81+
- be equal to: `py27`, `py34`, `py35`, `py36`, `py37`, `py38`
82+
- start with: `py27-`, `py34-`, `py35-`, `py36-`, `py37-`, `py38-`
83+
84+
- `image`: specify the Azure pipelines image to use (determines the OS target); if not specified
85+
we'll use the groups key name to assign one:
86+
- `linux` - `Ubuntu-16.04`
87+
- `windows` - `windows-2019`
88+
- `osx` - `macOS-latest`
89+
- otherwise `Ubuntu-16.04`
90+
- `architecture`: either `x64` or `x86`) with default `x64` (only affects windows)
91+
- `coverage`: if set after running the test suite tox will run this tox target to generate a coverage report.
92+
93+
Note: for now, `python3.8` is only available on linux -- it is installed from
94+
[deadsnakes](https://github.com/deadsnakes).
95+
96+
## `merge-coverage.yml`
97+
98+
This job template will download coverage files attached to the build (uploaded by `run-tox-env.yml`)
99+
and use target tox environment configured to generate a unified report. This then will be uploaded
100+
to the Azure Pipelines coverage report.
101+
102+
### example
103+
104+
```yaml
105+
- template: merge-coverage.yml@tox
106+
parameters:
107+
coverage: 'coverage'
108+
dependsOn:
109+
- windows
110+
- linux
111+
- macOs
112+
```
113+
114+
### parameters
115+
- `coverage` - tox target that generates the unified coverage report (default `coverage`)
116+
- `dependsOn` - environments this job depends on
117+
118+
## `publish-pypi.yml`
119+
120+
This job template will publish the Python package in the current folder (both sdist and wheel)
121+
via the PEP-517/8 build mechanism and twine.
122+
123+
### example
124+
125+
```yaml
126+
- ${{ if startsWith(variables['Build.SourceBranch'], 'refs/tags/') }}:
127+
- template: publish-pypi.yml@tox
128+
parameters:
129+
- external_feed: 'toxdev'
130+
- pypi_remote: 'pypi-toxdev'
131+
- dependsOn:
132+
- check
133+
- report_coverage
134+
```
135+
136+
### parameters
137+
- `external_feed` - the external feed to upload
138+
- `pypi_remote` - the pypi remote to upload to
139+
- `dependsOn` - environments this job depends on

‎merge-coverage.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,10 @@ jobs:
3939
shutil.copy(str(coverage_file), str(destination))'
4040
displayName: move coverage files into .tox
4141
42-
- script: "python -m pip install tox -U --user"
43-
displayName: upgrade pip
42+
- script: "python -m pip install -U --user --force-reinstall tox"
43+
displayName: install tox
4444

45-
- script: 'python -m tox -vv --sdistonly'
45+
- script: 'python -m tox -e py -vv --sdistonly'
4646
displayName: run package build to ensure generated files present
4747

4848
- script: 'python -m tox --notest -vv --skip-missing-interpreters false'

‎publish-pypi.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
- task: TwineAuthenticate@0
1919
inputs:
2020
externalFeeds: ${{ parameters.external_feed}}
21-
- script: 'python -m pip install pip -U; python -m pip install twine pep517 -U'
21+
- script: 'python -m pip install -U --user --force-reinstall twine pep517'
2222
displayName: "acquire build tools"
2323
- script: 'python -m pep517.build -m --binary --source --out-dir "$(System.DefaultWorkingDirectory)/w" .'
2424
displayName: "build wheel and source distribution"

‎run-tox-env.yml‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ jobs:
4141
${{ if eq(job.key, 'windows') }}:
4242
vmImage: 'windows-2019'
4343
${{ if eq(job.key, 'macOs') }}:
44-
vmImage: 'macOS-latest'
44+
vmImage: 'macOS-10.14'
4545
${{ if notIn(job.key, 'macOs', 'linux', 'windows') }}:
4646
vmImage: 'Ubuntu-16.04'
4747

@@ -66,7 +66,7 @@ jobs:
6666
- script: 'python -c "import sys; print(sys.version); print(sys.executable);"'
6767
displayName: show python information
6868

69-
- script: "python -m pip install -U tox --user"
69+
- script: "python -m pip install -U --user --force-reinstall tox"
7070
displayName: install tox
7171

7272
- script: 'python -m tox --notest -vv --skip-missing-interpreters false'
@@ -75,23 +75,27 @@ jobs:
7575
- script: 'python -m tox'
7676
displayName: run tox test environment
7777

78-
- bash: 'printf "##vso[task.setVariable variable=junit]" && ([ -f $(System.DefaultWorkingDirectory)/.tox/junit.$(TOXENV).xml ] && printf yes || printf no) && echo ""'
78+
- bash: 'printf "##vso[task.setVariable variable=junit]" && ([ -f junit.$(TOXENV).xml ] && printf yes || printf no) && echo ""'
79+
condition: always()
7980
displayName: check if junit file present
81+
workingDirectory: '$(System.DefaultWorkingDirectory)/.tox'
8082

8183
- task: PublishTestResults@2
8284
displayName: publish test results via junit
8385
condition: eq(variables.junit, 'yes')
8486
inputs:
8587
testResultsFormat: "JUnit"
8688
testResultsFiles: '.tox/junit.$(TOXENV).xml'
87-
testRunTitle: ${{ format('{0}-$(TOXENV)', job.value.image) }}
89+
testRunTitle: 'junit-$(Agent.OS)-$(Agent.OSArchitecture)-$(TOXENV)'
8890

8991
- ${{ if job.value.coverage }}:
9092
- script: ${{ format('python -m tox -e {0}', job.value.coverage) }}
9193
displayName: create coverag report
9294

93-
- bash: 'printf "##vso[task.setVariable variable=coverage]" && ([ -f $(System.DefaultWorkingDirectory)/.tox/coverage.xml -o -f $(System.DefaultWorkingDirectory)/.tox/.coverage ] && printf yes || printf no) && echo ""'
95+
- bash: 'printf "##vso[task.setVariable variable=coverage]" && ([ -f coverage.xml -o -f .coverage ] && printf yes || printf no) && echo ""'
9496
displayName: check if coverage file present
97+
condition: always()
98+
workingDirectory: '$(System.DefaultWorkingDirectory)/.tox'
9599

96100
- task: CopyFiles@2
97101
displayName: move coverage files into staging area
@@ -108,4 +112,4 @@ jobs:
108112
condition: eq(variables.coverage, 'yes')
109113
inputs:
110114
pathtoPublish: $(Build.ArtifactStagingDirectory)
111-
ArtifactName: ${{ format('coverage-{0}-$(TOXENV)', job.value.image) }}
115+
ArtifactName: 'coverage-$(Agent.OS)-$(Agent.OSArchitecture)-$(TOXENV)'

0 commit comments

Comments
 (0)