Skip to content

Commit 47b2e82

Browse files
Chisanan232Chisanan232
authored
Merge pull request #13 from Chisanan232/develop
🎉🎊🍾 [New Feature] (docs) Add project README.
2 parents 9630d1d + 5691de1 commit 47b2e82

File tree

1 file changed

+266
-0
lines changed

1 file changed

+266
-0
lines changed

‎README.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# GitHub Action - Workflow template for Python library
2+
3+
[![github-action reusable workflows test](https://github.com/Chisanan232/GitHub-Action-Template-Python/actions/workflows/test-reusable-workflows.yaml/badge.svg)](https://github.com/Chisanan232/GitHub-Action-Template-Python/actions/workflows/test-reusable-workflows.yaml)
4+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache)](https://opensource.org/licenses/Apache-2.0)
5+
6+
7+
This is a GitHub Action workflow template for **_Python library_** project.
8+
9+
[Overview](#overview) | [Workflow template usages](#workflow-template-usages)
10+
<hr>
11+
12+
## Overview
13+
14+
In development of Python library, it configures the mostly same CI/CD processes again and again. That's the reason why I consider and implement
15+
this project. This project has some workflow templates for reusing in GitHub Action CI/CD processes so that it could reach some benefits:
16+
* Be more clear what thing to do in a job.
17+
* Be more clear and simpler of entire CI/CD work flow.
18+
* Be easier to read and configure at configurations of GitHub Action work flow.
19+
* It has greatly improved the GitHub Action configuration to be more reusable in multiple different projects (git repositories).
20+
21+
22+
## Workflow template usages
23+
24+
The usage of each workflow template.
25+
26+
* [_prepare_test_items.yaml_](#prepare_test_itemsyaml)
27+
* [_run_test_items_via_pytest.yaml_](#run_test_items_via_pytestyaml)
28+
* [_organize_all_testing_coverage_reports_with_different_os_and_py_version.yaml_](#organize_all_testing_coverage_reports_with_different_os_and_py_versionyaml)
29+
* [_organize_all_testing_reports_with_different_test_type.yaml_](#organize_all_testing_reports_with_different_test_typeyaml)
30+
* [_upload_test_report_to_codecov.yaml_](#upload_test_report_to_codecovyaml)
31+
* [_upload_code_report_to_codacy.yaml_](#upload_code_report_to_codacyyaml)
32+
33+
34+
#### _prepare_test_items.yaml_
35+
36+
* Description: Prepare the test items.
37+
* Options:
38+
39+
| option name | function content |
40+
|-------------|------------------------------------------------------|
41+
| shell_path | The path shell script for getting the testing items. |
42+
| shell_arg | Input arguments of the shell script. |
43+
44+
* Output:
45+
* all_test_items: All the test items it would run.
46+
47+
* How to use it?
48+
49+
Before use this workflow, it should prepare a shell script for getting the testing items.
50+
51+
```yaml
52+
prepare-testing-items_unit-test:
53+
# name: Prepare all unit test items
54+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/prepare_test_items.yaml@master
55+
with:
56+
shell_path: scripts/ci/get-unit-test-paths.sh
57+
shell_arg: unix
58+
```
59+
60+
And we could get this workflow output result via keyword _all_test_items_.
61+
62+
<hr>
63+
64+
#### _run_test_items_via_pytest.yaml_
65+
66+
* Description: Run testing by specific type with all test items via PyTest and generate its testing coverage report (it would save reports by _actions/upload-artifact@v3_).
67+
* Options:
68+
69+
| option name | function content |
70+
|----------------------|--------------------------------------------------------------------------------------------|
71+
| test_type | The testing type. In generally, it only has 2 options: _unit-test_ and _integration-test_. |
72+
| all_test_items_paths | The target paths of test items under test. |
73+
74+
* Output:
75+
76+
No, but it would save the testing coverage reports to provide after-process to organize and record.
77+
78+
* How to use it?
79+
80+
```yaml
81+
run_unit-test:
82+
# name: Run all unit test items
83+
needs: prepare-testing-items_unit-test
84+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/run_test_items_via_pytest.yaml@master
85+
with:
86+
test_type: unit-test
87+
all_test_items_paths: ${{needs.prepare-testing-items_unit-test.outputs.all_test_items}}
88+
```
89+
90+
Please take a look of option _all_test_items_paths_. You could find that it get the input result of
91+
previous workflow _prepare-testing-items_unit-test_ via below way:
92+
93+
${{needs.prepare-testing-items_unit-test.outputs.all_test_items}}
94+
95+
Character part _needs.prepare-testing-items_unit-test_ means it want to get something context info
96+
from needed workflow _prepare-testing-items_unit-test_, and the context it wants to get is _outputs_.
97+
And be more essentially, what outputs it want to use? It's _all_test_items_. Do you discover this keyword
98+
is provided by previous workflow? That is all testing items.
99+
100+
<hr>
101+
102+
#### _organize_all_testing_coverage_reports_with_different_os_and_py_version.yaml_
103+
104+
* Description: Organize all the testing coverage reports. (it would save reports by _actions/upload-artifact@v3_).
105+
* Options:
106+
107+
| option name | function content |
108+
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
109+
| test_type | The testing type. In generally, it only has 2 options: _unit-test_ and _integration-test_. |
110+
| generate_xml_report_finally | Something, it only has 1 test type currently. So it could let this option to be 'true' than it would generate XML report finally to let uploading process to use it directly. |
111+
112+
* Output:
113+
114+
No, but it would save the testing coverage reports (coverage.xml) to provide after-process to organize and record.
115+
116+
* How to use it?
117+
118+
```yaml
119+
unit-test_codecov:
120+
# name: Organize and generate the testing report and upload it to Codecov
121+
needs: run_unit-test
122+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/organize_all_testing_coverage_reports_with_different_os_and_py_version.yaml@master
123+
with:
124+
test_type: unit-test
125+
generate_xml_report_finally: true
126+
```
127+
128+
It would upload the organized report via _actions/upload-artifact@v3_. And it doesn't support customize options of _actions/upload-artifact@v3_ currently.
129+
130+
<hr>
131+
132+
#### _organize_all_testing_reports_with_different_test_type.yaml_
133+
134+
* Description: Organize all the testing coverage reports. (it would save reports by _actions/upload-artifact@v3_).
135+
* Options:
136+
137+
It has no input parameter.
138+
139+
* Output:
140+
141+
No, but it would save the testing coverage reports (coverage.xml) to provide after-process to organize and record.
142+
143+
* How to use it?
144+
145+
```yaml
146+
organize_all-test_codecov_and_generate_report:
147+
# name: Organize and generate the testing report and upload it to Codecov
148+
needs: [unit-test_codecov, integration-test_codecov]
149+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/organize_all_testing_reports_with_different_test_type.yaml@master
150+
```
151+
152+
This workflow is very close with another workflow _organize_all_testing_coverage_reports_with_different_os_and_py_version.yaml_.
153+
But they're different. In a software test, it may have one or more test types it would run to check the software quality.
154+
So let us consider below 2 scenarios:
155+
156+
First scenario, it has only one test. So the CI workflow would be like below:
157+
158+
get test items -> run test -> organize and generate testing report
159+
160+
Second one, it has 2 tests: _Unit test_ and _Integration test_:
161+
162+
get unit test items -> run unit test -> organize unit test report ------------------------
163+
|-> organize and generate final test report
164+
get integration test items -> run integration test -> organize integration test report ---
165+
166+
So it should organize testing coverage reports twice, first time is organizing report with one specific test type,
167+
another one time is organizing these 2 test types reports.
168+
Hence, the different is:
169+
* _organize_all_testing_coverage_reports_with_different_os_and_py_version.yaml_ is the first process to organize testing coverage reports.
170+
And it could set option _generate_xml_report_finally_ as _true_ to let the CI workflow be more clear and simpler if it has only one test type.
171+
* _organize_all_testing_reports_with_different_test_type.yaml_ is the second organizing process if it has 2 more test types in CI workflow.
172+
173+
<hr>
174+
175+
#### _upload_test_report_to_codecov.yaml_
176+
177+
* Description: Upload the testing coverage reports to Codecov.
178+
* Options:
179+
180+
It has 2 different types option could use:
181+
182+
_General option_:
183+
184+
| option name | function content |
185+
|---------------|-----------------------------------------------------------------------------------|
186+
| download_path | The path to download testing coverage reports via _actions/download-artifact@v3_. |
187+
| codecov_flags | The flags of the testing coverage report for Codecov. |
188+
| codecov_name | The name of the testing coverage report for Codecov. |
189+
190+
_Secret option_:
191+
192+
| option name | function content |
193+
|---------------|-----------------------------------------------------------------|
194+
| codecov_token | The API token for uploading testing coverage report to Codecov. |
195+
196+
* Output:
197+
198+
Nothing.
199+
200+
* How to use it?
201+
202+
Before run this workflow, please make sure testing coverage report is ready.
203+
204+
```yaml
205+
codecov_finish:
206+
# name: Organize and generate the testing report and upload it to Codecov
207+
needs: [unit-test_codecov]
208+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/upload_test_report_to_codecov.yaml@master
209+
secrets:
210+
codecov_token: ${{ secrets.CODECOV_TOKEN }}
211+
with:
212+
download_path: ./
213+
codecov_flags: unittests
214+
codecov_name: smoothcrawler-cluster_github-actions_test # optional
215+
```
216+
217+
* The badges would be generated after this workflow done:
218+
219+
[![codecov](https://codecov.io/gh/Chisanan232/GitHub-Action-Template-Python/branch/master/graph/badge.svg?token=wbPgJ4wxOl)](https://codecov.io/gh/Chisanan232/GitHub-Action-Template-Python)
220+
221+
<hr>
222+
223+
#### _upload_code_report_to_codacy.yaml_
224+
225+
* Description: Upload the testing coverage reports to Codacy.
226+
* Options:
227+
228+
It has 2 different types option could use:
229+
230+
_General option_:
231+
232+
| option name | function content |
233+
|---------------|-----------------------------------------------------------------------------------|
234+
| download_path | The path to download testing coverage reports via _actions/download-artifact@v3_. |
235+
236+
_Secret option_:
237+
238+
| option name | function content |
239+
|--------------|----------------------------------------------------------------|
240+
| codacy_token | The API token for uploading testing coverage report to Codacy. |
241+
242+
* Output:
243+
244+
Nothing.
245+
246+
* How to use it?
247+
248+
Before run this workflow, please make sure testing coverage report is ready.
249+
250+
```yaml
251+
codacy_finish:
252+
# name: Upload test report to Codacy to analyse and record code quality
253+
needs: [unit-test_codecov]
254+
uses: Chisanan232/GitHub-Action-Template-Python/.github/workflows/upload_code_report_to_codacy.yaml@master
255+
secrets:
256+
codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
257+
with:
258+
download_path: ./
259+
```
260+
261+
* The badges would be generated after this workflow done:
262+
263+
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/e8bfcd5830ba4232b45aca7c2d3e6310)](https://www.codacy.com/gh/Chisanan232/GitHub-Action-Template-Python/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=Chisanan232/GitHub-Action-Template-Python&amp;utm_campaign=Badge_Grade)
264+
[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/e8bfcd5830ba4232b45aca7c2d3e6310)](https://www.codacy.com/gh/Chisanan232/GitHub-Action-Template-Python/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Chisanan232/GitHub-Action-Template-Python&utm_campaign=Badge_Coverage)
265+
266+
<hr>

0 commit comments

Comments
 (0)