You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Here you'll find a contributing guide to get started with development.
4
+
3
5
## Environment
4
6
5
-
For local development, it is required to have Python 3.8 (or a later version) installed.
7
+
For local development, it is required to have Python 3.9 (or a later version) installed.
8
+
9
+
We use [Poetry](https://python-poetry.org/) for project management. Install it and set up your IDE accordingly.
6
10
7
-
It is recommended to set up a virtual environment while developing this package to isolate your development environment,
8
-
however, due to the many varied ways Python can be installed and virtual environments can be set up,
9
-
this is left up to the developers to do themselves.
11
+
## Dependencies
10
12
11
-
One recommended way is with the built-in `venv` module:
13
+
To install this package and its development dependencies, run:
12
14
13
-
```bash
14
-
python3 -m venv .venv
15
-
source .venv/bin/activate
15
+
```sh
16
+
make install-dev
16
17
```
17
18
18
-
To improve on the experience, you can use [pyenv](https://github.com/pyenv/pyenv) to have an environment with a pinned Python version,
19
-
and [direnv](https://github.com/direnv/direnv) to automatically activate/deactivate the environment when you enter/exit the project folder.
19
+
## Code checking
20
20
21
-
## Dependencies
21
+
To execute all code checking tools together, run:
22
22
23
-
To install this package and its development dependencies, run `make install-dev`.
23
+
```sh
24
+
make check-code
25
+
```
24
26
25
-
##Code checking
27
+
### Linting
26
28
27
-
To run all our code checking tools together, just run `make check-code`.
29
+
We utilize [ruff](https://docs.astral.sh/ruff/) for linting, which analyzes code for potential issues and enforces consistent style. Refer to `pyproject.toml` for configuration details.
28
30
29
-
### Linting
31
+
To run linting:
30
32
31
-
We use [ruff](https://docs.astral.sh/ruff/) for linting to to analyze the code for potential issues and enforce
32
-
uniformed code style. See the `pyproject.toml` for its configuration. To run the linting, just run `make lint`.
33
+
```sh
34
+
make lint
35
+
```
33
36
34
37
### Formatting
35
38
36
-
We use [ruff](https://docs.astral.sh/ruff/) for automated code formatting. It formats the code to follow uniformed
37
-
code style and addresses auto-fixable linting issues. See the `pyproject.toml` for its configuration. To run
38
-
the formatting, just run `make format`.
39
+
Our automated code formatting also leverages [ruff](https://docs.astral.sh/ruff/), ensuring uniform style and addressing fixable linting issues. Configuration specifics are outlined in `pyproject.toml`.
40
+
41
+
To run formatting:
42
+
43
+
```sh
44
+
make format
45
+
```
39
46
40
47
### Type checking
41
48
42
-
We use [mypy](https://mypy.readthedocs.io/en/stable/) for type checking. See the `mypy.ini` for its configuration.
43
-
To run the type checking, just run `make type-check`.
49
+
Type checking is handled by [mypy](https://mypy.readthedocs.io/), verifying code against type annotations. Configuration settings can be found in `pyproject.toml`.
50
+
51
+
To run type checking:
52
+
53
+
```sh
54
+
make type-check
55
+
```
44
56
45
57
### Unit tests
46
58
47
-
We use [pytest](https://docs.pytest.org/) as a testing framework with many plugins. See the `pyproject.toml` for
48
-
both its configuration and the list of installed plugins. To run unit tests execute `make unit-tests`. To run unit
49
-
tests with HTML coverage report execute `make unit-tests-cov`.
59
+
We employ pytest as our testing framework, equipped with various plugins. Check pyproject.toml for configuration details and installed plugins.
60
+
61
+
We use [pytest](https://docs.pytest.org/) as a testing framework with many plugins. Check `pyproject.toml` for configuration details and installed plugins.
62
+
63
+
To run unit tests:
64
+
65
+
```sh
66
+
make unit-tests
67
+
```
68
+
69
+
To run unit tests with HTML coverage report:
70
+
71
+
```sh
72
+
make unit-tests-cov
73
+
```
50
74
51
75
## Integration tests
52
76
@@ -59,82 +83,84 @@ the `APIFY_INTEGRATION_TESTS_API_URL` environment variable to the right URL to t
59
83
60
84
## Documentation
61
85
62
-
We use the [Google docstring format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for documenting the code.
63
-
We document every user-facing class or method, and enforce that using the flake8-docstrings library.
86
+
We adhere to the [Google docstring format](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for documenting our codebase. Every user-facing class or method is documented. Documentation standards are enforced using [Ruff](https://docs.astral.sh/ruff/).
64
87
65
-
The documentation is then rendered from the docstrings in the code, using `pydoc-markdown` and some heavy post-processing,
66
-
and from Markdown documents in the `docs` folder in the `docs` branch, and then rendered using Docusaurus and published to GitHub pages.
88
+
Our API documentation is generated from these docstrings using [pydoc-markdown](https://pypi.org/project/pydoc-markdown/) with additional post-processing. Markdown files in the `docs/` folder complement the autogenerated content. Final documentation is rendered using [Docusaurus](https://docusaurus.io/) and published to GitHub Pages.
67
89
68
-
## Release process
90
+
To run the documentation locally, you need to have Node.js version 20 or higher installed. Once you have the correct version of Node.js, follow these steps:
69
91
70
-
Publishing new versions to [PyPI](https://pypi.org/project/apify) happens automatically through GitHub Actions.
92
+
Navigate to the `website/` directory:
71
93
72
-
On each commit to the `master` branch, a new beta release is published, taking the version number from `pyproject.toml`
73
-
and automatically incrementing the beta version suffix by 1 from the last beta release published to PyPI.
94
+
```sh
95
+
cd website/
96
+
```
74
97
75
-
A stable version is published when a new release is created using GitHub Releases, again taking the version number from `pyproject.toml`.
76
-
The built package assets are automatically uploaded to the GitHub release.
98
+
Enable Corepack, which installs Yarn automatically:
77
99
78
-
If there is already a stable version with the same version number as in `pyproject.toml` published to PyPI, the publish process fails,
79
-
so don't forget to update the version number before releasing a new version.
80
-
The release process also fails when the released version is not described in `CHANGELOG.md`,
81
-
so don't forget to describe the changes in the new version there.
100
+
```sh
101
+
corepack enable
102
+
```
82
103
83
-
### Beta release checklist
104
+
Build the API reference:
84
105
85
-
Beta release happens automatically after you merge a pull request or add a direct commit to the master branch. Before you do that check the following:
106
+
```sh
107
+
./build_api_reference.sh
108
+
```
86
109
87
-
- Make sure that in the [pyproject.toml](https://github.com/apify/apify-sdk-python/blob/master/pyproject.toml) a project version is set to the latest non-published version.
88
-
- Describe your changes to the [CHANGELOG.md](https://github.com/apify/apify-sdk-python/blob/master/CHANGELOG.md) in the section with the latest non-published version.
110
+
Install the necessary dependencies:
89
111
90
-
### Production release checklist
112
+
```sh
113
+
yarn
114
+
```
91
115
92
-
Production release happens after the GitHub release is created. Before you do that check the following:
116
+
Start the project in development mode with Hot Module Replacement (HMR):
93
117
94
-
- Make sure [here](https://pypi.org/project/apify/#history) that the beta release with the latest commit is successfully deployed.
95
-
- Make sure that all the changes that happened from the last production release are described in the [CHANGELOG.md](https://github.com/apify/apify-sdk-python/blob/master/CHANGELOG.md) (it's okay to skip DX related changes, repo setup etc).
96
-
- When drafting a new GitHub release:
97
-
- Create a new tag in the format of `v1.2.3` targeting the master branch.
98
-
- Fill in the release title in the format of `1.2.3`.
99
-
- Copy the changes from the [CHANGELOG.md](https://github.com/apify/apify-sdk-python/blob/master/CHANGELOG.md) and paste them into the release description. Make sure that all changes are properly categorized using headlines (`Added`, `Fixed` or `Internal changes`).
100
-
- Check the "Set as the latest release" option.
118
+
```sh
119
+
yarn start
120
+
```
101
121
102
-
Currently, there is no explicit approval process, so when you are done with the checklist, proceed with the release.
122
+
Or using `make`:
103
123
104
-
Once released, manually bump the version in `pyproject.toml` ([PR example](https://github.com/apify/apify-sdk-python/pull/187)).
124
+
```sh
125
+
make run-doc
126
+
```
127
+
128
+
## Release process
105
129
106
-
## Maintanance
130
+
Publishing new versions to [PyPI](https://pypi.org/project/apify) is automated through GitHub Actions.
107
131
108
-
### Removing Support for an outdated Python version
132
+
-**Beta releases**: On each commit to the master branch, a new beta release is automatically published. The version number is determined based on the latest release and conventional commits. The beta version suffix is incremented by 1 from the last beta release on PyPI.
133
+
-**Stable releases**: A stable version release may be created by triggering the `release` GitHub Actions workflow. The version number is determined based on the latest release and conventional commits (`auto` release type), or it may be overriden using the `custom` release type.
109
134
110
-
- Todo: Fill in once Python 3.8 is deprecated.
135
+
### Publishing to PyPI manually
111
136
112
-
### Adding support for a new Python version
137
+
1.**Do not do this unless absolutely necessary.** In all conceivable scenarios, you should use the `release` workflow instead.
0 commit comments