Skip to content

Commit 1665473

Browse files
hnroberthnrobert
committed
docs: add more spec
1 parent 25c0895 commit 1665473

File tree

1 file changed

+191
-13
lines changed

1 file changed

+191
-13
lines changed

‎README.md‎

Lines changed: 191 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,205 @@ Structure:
66

77
```text
88
app/
9-
└─ hello.py
9+
└─ hello.py
1010
tests/
11-
└─ test_hello.py
11+
└─ test_hello.py
1212
requirements.txt
13-
.github/workflows/test.yml
13+
.github/
14+
└─ workflows/
15+
├─ test.yml
16+
├─ package.yml
17+
├─ package-matrix.yml
18+
└─ release.yml
1419
```
1520

16-
This example intentionally does not include a packaging workflow; you'll add it as a hands-on exercise.
21+
This example includes a package workflow; you'll implement it as a hands-on exercise.
1722

18-
## Local packaging
23+
## Reading a simple workflow - test.yml
24+
25+
### First to know: about YAML syntax
26+
27+
YAML is a human-friendly data serialization standard for all programming languages. It is commonly used for configuration files and in applications where data is being stored or transmitted.
28+
29+
- Key-Value Pairs: Data is represented as key-value pairs, separated by a colon and a space (`key: value`).
30+
31+
```yaml
32+
name: CI — Test & Lint
33+
```
34+
35+
> PS: In YAML, strings do not need to be enclosed in quotes unless they contain special characters.
36+
> For example, all of the following four lines are valid in YAML:
37+
>
38+
> ```yaml
39+
> greeting: Hello
40+
> greeting: Hello World
41+
> greeting: "Hello World"
42+
> path: "/home/user/my folder"
43+
> ```
44+
>
45+
> Here, `greeting` does not need quotes, but `path` uses quotes because the value contains a space.
46+
> So THIS is NOT valid:
47+
>
48+
> ```yaml
49+
> path: /home/user/my folder # ❌
50+
> ```
51+
52+
- Indentation: YAML uses indentation (spaces) to denote structure. Consistent indentation is crucial; typically, two spaces are used per level.
53+
- Nested Structures: Indentation indicates nesting. For example:
54+
55+
```yaml
56+
on:
57+
push:
58+
```
59+
60+
- Lists: Lists are denoted by a hyphen and a space (`- item`). It can also be defined in-line using square brackets (`[item1, item2]`).
61+
62+
```yaml
63+
branches:
64+
- main
65+
- develop
66+
```
67+
68+
**Or**
69+
70+
```yaml
71+
branches: [main, develop]
72+
```
73+
74+
Within a list, each item can be a simple value or a complex structure (like another key-value pair).
75+
76+
```yaml
77+
steps:
78+
- name: Checkout Repo
79+
uses: actions/checkout@v4
80+
- name: Set up Python
81+
uses: actions/setup-python@v4
82+
```
83+
84+
If we convert the above to JSON, it would look like this:
85+
86+
```json
87+
"steps": [
88+
{
89+
"name": "Checkout Repo",
90+
"uses": "actions/checkout@v4"
91+
},
92+
{
93+
"name": "Set up Python",
94+
"uses": "actions/setup-python@v4"
95+
}
96+
]
97+
```
98+
99+
- Comments: Lines starting with `#` are comments and are ignored by parsers.
100+
101+
```yaml
102+
# This is a comment
103+
```
104+
105+
**Congrats!** You now have a basic understanding of YAML syntax, which is enough for you to read and understand GitHub Actions workflow files.
106+
107+
### Breakdown of test.yml
108+
109+
Let's break down the `test.yml` workflow file located in `.github/workflows/test.yml`.
110+
111+
#### Workflow Name and Trigger
112+
113+
```yaml
114+
name: CI — Test & Lint
115+
116+
on:
117+
push:
118+
branches: [main]
119+
pull_request:
120+
branches: [main]
121+
```
122+
123+
This section defines when the workflow will run. It triggers on pushes and pull requests to the `main` branch.
124+
125+
`push` events occur when code (new commits / updates to previous commits) is pushed to the repository, while `pull_request` events happen when a pull request is opened or updated.
126+
127+
To use a `pull_request` trigger, you typically need to fork the repository, make changes in your fork, and then create a pull request back to the original repository.
128+
The owner of the original repository can then review and merge your changes based on the results of the workflow triggered by the pull request.
129+
130+
#### Jobs
131+
132+
Now let's look at the job definition:
133+
134+
```yaml
135+
jobs:
136+
test:
137+
runs-on: ubuntu-latest
138+
steps:
139+
# Checkout the repository - Add this step at the beginning of the steps to help the Job access the code
140+
- name: Checkout Repo
141+
uses: actions/checkout@v4
142+
143+
# ...
144+
```
145+
146+
This section defines a job named `test` that runs on the latest Ubuntu environment.
147+
148+
To define a job in GitHub Actions, you use the `jobs` keyword followed by a unique identifier for the job (in this case, `test`). Each job can have several properties, including:
149+
150+
- `runs-on`: Specifies the type of virtual machine to run the job on (e.g., `ubuntu-latest`, `windows-latest`, `macos-latest`).
151+
- GitHub Actions provides a variety of hosted runners with different operating systems and configurations. The three most common options are:
152+
- `ubuntu-latest`: The latest stable version of Ubuntu Linux.
153+
- `windows-latest`: The latest stable version of Windows Server.
154+
- `macos-latest`: The latest stable version of macOS.
155+
You can choose a appropriate runner according to [the docs provided by GitHub](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job#choosing-github-hosted-runners) based on your project's requirements and the environment you need for your workflows.
156+
- `steps`: A list of steps that make up the job. Each step can either run a script or use an action.
157+
158+
#### Steps
159+
160+
The `steps` section contains a series of actions that the job will perform.
161+
162+
The following is the complete `steps` section with comments explaining each step
163+
164+
```yaml
165+
steps:
166+
# Checkout the repository - Add this step at the beginning of the steps to help the Job access the code
167+
# This is a common first step in most workflows that need to work with the repository's code.
168+
- name: Checkout Repo
169+
uses: actions/checkout@v4
170+
171+
# Set up Python environment - Automatically install Python for the job efficiently
172+
# In this way, you don't need to manually install Python using shell commands
173+
# This action step handles it for you.
174+
- name: Set up Python
175+
uses: actions/setup-python@v4
176+
with:
177+
python-version: "3.11"
178+
179+
# Install dependencies
180+
# This step ensures that all necessary Python packages listed in requirements.txt are installed
181+
- name: Install dependencies
182+
run: |
183+
python -m pip install --upgrade pip
184+
pip install -r requirements.txt
185+
186+
# Run linting - Check code style using autopep8
187+
# This is a common practice to maintain code quality and consistency.
188+
- name: Run autopep8 check
189+
run: |
190+
pip install autopep8
191+
autopep8 --diff --recursive app tests
192+
193+
# Run tests - Execute the test suite using pytest.
194+
# If everything passes, the step will succeed, the job will succeed,
195+
# else they will all fail eventually and issues will be reported.
196+
- name: Run tests
197+
env:
198+
PYTHONPATH: ${{ github.workspace }}
199+
run: pytest -q
200+
```
201+
202+
## Local packaging for this project
19203

20204
You can quickly build a standalone executable for this small project with PyInstaller.
21205

206+
> It is not necessary for you to run this locally, as the packaging step today will be done in GitHub Actions, but if you want to try it out, follow these steps.
207+
22208
On macOS/Linux:
23209

24210
```bash
@@ -45,14 +231,6 @@ You can try implement a simple sequential workflow that first builds macOS arm64
45231

46232
If you have finished composing or encountered some troubles, you may see `solutions/package.yml` — this builds the two packages in sequence and uploads two artifacts (`hello-macos-arm64` and `hello-windows-x64`).
47233

48-
There is also a enhanced version that uses a matrix to build multiple Python versions and OSes in parallel in `.github/workflows/package-matrix.yml`. You may check it out after finishing the exercise.
49-
50-
Steps:
51-
52-
1. Copy `solutions/package.yml` into `.github/workflows/package.yml`.
53-
2. Commit and push; this will trigger the workflow via `workflow_dispatch` if you run it manually, or on `push` tags.
54-
3. Check the workflow run and download artifacts from the run summary.
55-
56234
## Release flow (automatic packaging and release assets)
57235

58236
The repository includes a pair of workflows to create a tag, publish a release, and attach build artifacts to the release:

0 commit comments

Comments
 (0)