Skip to content

Commit e81b0c5

Browse files
WilliamBergaminWilliamBergamin
authored
feat: setup maintainable project (#2)
* Set up project for maintainer contribution
1 parent 403311e commit e81b0c5

31 files changed

Lines changed: 601 additions & 55 deletions

‎.flake8‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[flake8]
2+
max-line-length = 125

‎.github/maintainers_guide.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Maintainers Guide
2+
3+
This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
4+
this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
5+
**not** for you.
6+
7+
## Tools
8+
9+
### Python (and friends)
10+
11+
We recommend using [pyenv](https://github.com/pyenv/pyenv) for Python runtime management. If you use macOS, follow the following steps:
12+
13+
```zsh
14+
brew update
15+
brew install pyenv
16+
```
17+
18+
Install necessary Python runtimes for development/testing. You can rely on GitHub Actions for testing with various major versions.
19+
20+
```zsh
21+
pyenv install -l | grep -v "-e[conda|stackless|pypy]"
22+
23+
pyenv install 3.8.5 # select the latest patch version
24+
pyenv local 3.8.5
25+
26+
pyenv versions
27+
system
28+
3.6.10
29+
3.7.7
30+
* 3.8.5 (set by /path-to-python-slack-hooks/.python-version)
31+
32+
pyenv rehash
33+
```
34+
35+
Then, you can create a new Virtual Environment this way:
36+
37+
```zsh
38+
python -m venv env_3.8.5
39+
source env_3.8.5/bin/activate
40+
```
41+
42+
## Tasks
43+
44+
### Testing
45+
46+
#### Run All the Unit Tests
47+
48+
If you make some changes to this project, please write corresponding unit tests as much as possible. You can easily run all the tests by running the following scripts.
49+
50+
If this is your first time to run tests, although it may take a bit longer, running the following script is the easiest.
51+
52+
```zsh
53+
./scripts/install_and_run_tests.sh
54+
```
55+
56+
To simply install all the development dependencies for this project.
57+
58+
```zsh
59+
./scripts/install.sh
60+
```
61+
62+
Once you installed all the required dependencies, you can use the following.
63+
64+
```zsh
65+
./scripts/run_tests.sh
66+
./scripts/run_tests.sh tests/scenario_test/test_get_hooks.py
67+
```
68+
69+
To format this project
70+
71+
```zsh
72+
./scripts/format.sh
73+
```
74+
75+
To lint this project
76+
77+
```zsh
78+
./scripts/lint.sh
79+
```
80+
81+
This project uses [pytype](https://google.github.io/pytype/) to check and infers types for your Python code.
82+
83+
```zsh
84+
./scripts/run_pytype.sh
85+
```
86+
87+
#### Develop Locally
88+
89+
If you want to test the package locally you can.
90+
91+
1. Build the package locally
92+
- Run
93+
94+
```zsh
95+
scripts/build_pypi_package.sh
96+
```
97+
98+
- This will create a `.whl` file in the `./dist` folder
99+
2. Use the built package
100+
- Example `/dist/slack_cli_hooks-1.2.3-py2.py3-none-any.whl` was created
101+
- From anywhere on your machine you can install this package to a project with
102+
103+
```zsh
104+
pip install <project path>/dist/slack_cli_hooks-1.2.3-py2.py3-none-any.whl
105+
```
106+
107+
### Releasing
108+
109+
#### test.pypi.org deployment
110+
111+
It is possible to deploy this project on <https://test.pypi.org/> in order to try out packaging and deploy related changes
112+
113+
```zsh
114+
./scripts/deploy_to_test_pypi.sh
115+
```
116+
117+
#### Development Deployment
118+
119+
1. Create a branch in which the development release will live:
120+
- Bump the version number in adherence to [Semantic Versioning](http://semver.org/) and [Developmental Release](https://peps.python.org/pep-0440/#developmental-releases) in `slack_cli_hooks/version.py`
121+
- Example the current version is `1.2.3` a proper development bump would be `1.3.0.dev0`
122+
- `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
123+
- Note that the `dev` version can be bumped in development releases: `1.3.0.dev0` -> `1.3.0.dev1`
124+
- Commit with a message including the new version number. For example `1.3.0.dev0` & Push the commit to a branch where the development release will live (create it if it does not exist)
125+
- `git checkout -b future-release`
126+
- `git commit -m 'version 1.3.0.dev0'`
127+
- `git push future-release`
128+
- Create a git tag for the release. For example `git tag v1.3.0.dev0`.
129+
- Push the tag up to github with `git push origin --tags`
130+
131+
2. Distribute the release
132+
- Use the latest stable Python runtime
133+
- `python -m venv .venv`
134+
- `./scripts/deploy_to_prod_pypi.sh`
135+
- You do not need to create a GitHub release
136+
137+
3. (Slack Internal) Communicate the release internally
138+
139+
#### Production Deployment
140+
141+
1. Create the commit for the release:
142+
- Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `slack_cli_hooks/version.py`
143+
- Commit with a message including the new version number. For example `1.2.3` & Push the commit to a branch and create a PR to sanity check.
144+
- `git checkout -b v1.2.3-release`
145+
- `git commit -m 'version 1.2.3'`
146+
- `git push {your-fork} v1.2.3-release`
147+
- Merge in release PR after getting an approval from at least one maintainer.
148+
- Create a git tag for the release. For example `git tag v1.2.3`.
149+
- Push the tag up to github with `git push origin --tags`
150+
151+
2. Distribute the release
152+
- Use the latest stable Python runtime
153+
- `python -m venv .venv`
154+
- `./scripts/deploy_to_pypi_org.sh`
155+
- Create a GitHub release - <https://github.com/slackapi/python-slack-hooks/releases>
156+
157+
```markdown
158+
## New Features
159+
160+
### Awesome Feature 1
161+
162+
Description here.
163+
164+
### Awesome Feature 2
165+
166+
Description here.
167+
168+
## Changes
169+
170+
* #123 Make it better - thanks @SlackHQ
171+
* #123 Fix something wrong - thanks @seratch
172+
```
173+
174+
3. (Slack Internal) Communicate the release internally
175+
- Include a link to the GitHub release
176+
177+
4. (Slack Internal) Tweet by @SlackAPI
178+
- Not necessary for patch updates, might be needed for minor updates, definitely needed for major updates. Include a link to the GitHub release
179+
180+
## Workflow
181+
182+
### Versioning and Tags
183+
184+
This project uses semantic versioning, expressed through the numbering scheme of
185+
[PEP-0440](https://www.python.org/dev/peps/pep-0440/).
186+
187+
### Branches
188+
189+
`main` is where active development occurs. Long running named feature branches are occasionally created for
190+
collaboration on a feature that has a large scope (because everyone cannot push commits to another person's open Pull
191+
Request). At some point in the future after a major version increment, there may be maintenance branches for older major
192+
versions.
193+
194+
### Issue Management
195+
196+
Labels are used to run issues through an organized workflow. Here are the basic definitions:
197+
198+
- `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been
199+
documented and the issue has been reproduced.
200+
- `enhancement`: A feature request for something this package might not already do.
201+
- `docs`: An issue that is purely about documentation work.
202+
- `tests`: An issue that is purely about testing work.
203+
- `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
204+
- `question`: An issue that is like a support request because the user's usage was not correct.
205+
206+
**Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic level of information
207+
with labels. An issue should have **one** of the following labels applied: `bug`, `enhancement`, `question`,
208+
`needs feedback`, `docs`, `tests`, or `discussion`.
209+
210+
Issues are closed when a resolution has been reached. If for any reason a closed issue seems relevant once again,
211+
reopening is great and better than creating a duplicate issue.
212+
213+
## Everything else
214+
215+
When in doubt, find the other maintainers and ask.

‎.github/workflows/codecov.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Run codecov
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
timeout-minutes: 10
12+
strategy:
13+
matrix:
14+
python-version: ["3.12"]
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Set up Python ${{ matrix.python-version }}
18+
uses: actions/setup-python@v4
19+
with:
20+
python-version: ${{ matrix.python-version }}
21+
- name: Install dependencies
22+
run: |
23+
pip install -U pip
24+
pip install .
25+
pip install -r requirements/testing.txt
26+
- name: Run all tests for codecov
27+
run: |
28+
pytest --cov=./slack_cli_hooks/ --cov-report=xml
29+
# TODO uncomment when repo public
30+
# - name: Upload coverage to Codecov
31+
# uses: codecov/codecov-action@v3
32+
# with:
33+
# fail_ci_if_error: true
34+
# verbose: true

‎.github/workflows/flake8.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Run flake8 validation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
timeout-minutes: 2
12+
strategy:
13+
matrix:
14+
python-version: ["3.12"]
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Set up Python ${{ matrix.python-version }}
18+
uses: actions/setup-python@v4
19+
with:
20+
python-version: ${{ matrix.python-version }}
21+
- name: Run flake8 verification
22+
run: |
23+
./scripts/lint.sh

‎.github/workflows/pytype.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Run pytype validation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
timeout-minutes: 2
12+
strategy:
13+
matrix:
14+
python-version: ["3.11"]
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Set up Python ${{ matrix.python-version }}
18+
uses: actions/setup-python@v4
19+
with:
20+
python-version: ${{ matrix.python-version }}
21+
- name: Run pytype verification
22+
run: |
23+
./scripts/run_pytype.sh

‎.github/workflows/tests.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Run all the unit tests
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
# Avoiding -latest due to https://github.com/actions/setup-python/issues/162
11+
runs-on: ubuntu-20.04
12+
timeout-minutes: 5
13+
strategy:
14+
matrix:
15+
python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Set up Python ${{ matrix.python-version }}
19+
uses: actions/setup-python@v4
20+
with:
21+
python-version: ${{ matrix.python-version }}
22+
- name: Install dependencies
23+
run: |
24+
pip install -U pip
25+
pip install .
26+
pip install -r requirements/testing.txt
27+
- name: Run tests
28+
run: |
29+
pytest

‎.github/workflows/triage-issues.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# This workflow uses the following github action to automate
2+
# management of stale issues and prs in this repo:
3+
# https://github.com/marketplace/actions/close-stale-issues
4+
5+
name: Close stale issues and PRs
6+
7+
on:
8+
workflow_dispatch:
9+
schedule:
10+
- cron: "0 0 * * 1"
11+
12+
permissions:
13+
issues: write
14+
pull-requests: write
15+
16+
jobs:
17+
stale:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/stale@v8
21+
with:
22+
days-before-issue-stale: 30
23+
days-before-issue-close: 10
24+
days-before-pr-stale: -1
25+
days-before-pr-close: -1
26+
stale-issue-label: auto-triage-stale
27+
stale-issue-message: 👋 It looks like this issue has been open for 30 days with no activity. We'll mark this as stale for now, and wait 10 days for an update or for further comment before closing this issue out. If you think this issue needs to be prioritized, please comment to get the thread going again! Maintainers also review issues marked as stale on a regular basis and comment or adjust status if the issue needs to be reprioritized.
28+
close-issue-message: As this issue has been inactive for more than one month, we will be closing it. Thank you to all the participants! If you would like to raise a related issue, please create a new issue which includes your specific details and references this issue number.
29+
exempt-issue-labels: auto-triage-skip
30+
exempt-all-milestones: true
31+
remove-stale-when-updated: true
32+
enable-statistics: true
33+
operations-per-run: 60

0 commit comments

Comments
 (0)