Skip to content

Commit d713717

Browse files
AhzyuanAhzyuan
committed
Add 🗃 Project management, i.e. template for issues and PR
1 parent 946943d commit d713717

File tree

7 files changed

+338
-5
lines changed

7 files changed

+338
-5
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Contribution Guidelines
2+
3+
𝐓𝐡𝐚𝐧𝐤 𝐲𝐨𝐮 𝐟𝐨𝐫 𝐲𝐨𝐮𝐫 𝐜𝐨𝐧𝐭𝐫𝐢𝐛𝐮𝐭𝐢𝐨𝐧 𝐭𝐨 𝐭𝐡𝐞 𝐩𝐫𝐨𝐣𝐞𝐜𝐭!
4+
𝐖𝐞 𝐰𝐚𝐫𝐦𝐥𝐲 𝐰𝐞𝐥𝐜𝐨𝐦𝐞 𝐲𝐨𝐮 𝐭𝐨 𝐚𝐬𝐤 𝐪𝐮𝐞𝐬𝐭𝐢𝐨𝐧𝐬, 𝐫𝐞𝐩𝐨𝐫𝐭 𝐞𝐫𝐫𝐨𝐫𝐬 𝐨𝐫 𝐬𝐮𝐛𝐦𝐢𝐭 𝐜𝐨𝐝𝐞.
5+
𝐏𝐥𝐞𝐚𝐬𝐞 𝐟𝐨𝐥𝐥𝐨𝐰 𝐭𝐡𝐞 𝐟𝐨𝐥𝐥𝐨𝐰𝐢𝐧𝐠 𝐬𝐭𝐞𝐩𝐬 𝐭𝐨 𝐨𝐩𝐞𝐫𝐚𝐭𝐞.
6+
7+
## 💬 Issues
8+
9+
1. If you **find a bug** or **have a feature request**, submit a detailed description following provided issue template in the `issue` page.
10+
11+
2. 𝐓𝐡𝐞 𝐨𝐯𝐞𝐫𝐚𝐥𝐥 𝐩𝐫𝐨𝐜𝐞𝐬𝐬 𝐢𝐧𝐜𝐥𝐮𝐝𝐞𝐬:
12+
- Check if same issue exists.
13+
- Describe what you encountered and expected.
14+
- Steps to reproduce the problem.
15+
- The environment where the problem occurs (operating system, package version, etc.)
16+
- Other information, such as screenshots, logs, etc.
17+
18+
> [!IMPORTANT]
19+
> Please ensure to provide sufficient information,
20+
> so that we can reproduce the problem or understand the functional requirements.
21+
22+
## 📤 Pull Request
23+
24+
1. 𝐌𝐚𝐢𝐧 𝐬𝐭𝐞𝐩𝐬
25+
- Fork the repository to your own GitHub account.
26+
- Clone the forked repository to your local machine.
27+
- **Create a new branch for your contribution.**
28+
- Make your changes and commit them to your new branch.
29+
- Push your changes to your forked repository.
30+
- Create a `Pull Request(PR)` from your forked repository to the original repository.
31+
- Wait for the PR to be reviewed and merged.
32+
33+
2. 𝐏𝐨𝐢𝐧𝐭𝐬 𝐭𝐨 𝐧𝐨𝐭𝐞
34+
35+
- **Branching management**: Before making code contributions, create a new branch from the `master` branch and give it a descriptive name.
36+
37+
- **Code style**:
38+
- Follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) code specification.。
39+
- Ensure that the code has good readability and maintainability.
40+
- Add comments for complex logic and non-obvious code.
41+
42+
- **Code test**:
43+
- Please add appropriate tests to your code.
44+
- Ensure that the test covers your new function or fixed bug.
45+
- Before submitting code, run all tests and ensure they pass.
46+
47+
- **Submit a `Pull Request(PR)`**:
48+
> Please clearly explain the following content according to the provided PR template
49+
- Your contribution content, including the problems solved or functions added.
50+
- If you have fixed the issue, please reference it.
51+
- Test methods, steps and results
52+
- Other information, such as screenshots, logs, etc.
53+
54+
## 🧐 Code review
55+
56+
- **All PRs will go through code review**. Other developers may offer suggestions and feedback to improve the quality of the code.
57+
- **Please actively participate in the code review process**, reply to the reviewer's questions and suggestions, and make modifications as needed.
58+
59+
## 📜 Code of conduct
60+
61+
- Please abide by [GitHub's code of conduct](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines) and the **terms of this project's open source license**.
62+
- **Maintain respect and courtesy in communication**. Avoid offensive language and personal attacks.
63+
- Different viewpoints and opinions are welcome, but please discuss **in a constructive way**.
64+
65+
## 🤝 Acknowledgement
66+
67+
𝓦𝓮 𝓪𝓻𝓮 𝓮𝔁𝓽𝓻𝓮𝓶𝓮𝓵𝔂 𝓰𝓻𝓪𝓽𝓮𝓯𝓾𝓵 𝓽𝓸 𝓪𝓵𝓵 𝓬𝓸𝓷𝓽𝓻𝓲𝓫𝓾𝓽𝓸𝓻𝓼 **!**
68+
69+
Your efforts and contributions have made this project better. If your contribution is accepted, **you will be included in the list of contributors to the project.**

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Bug Report
2+
description: File a bug report.
3+
title: "[🐞 Bug]: "
4+
labels: ["bug", "triage"]
5+
6+
body:
7+
8+
- type: markdown
9+
attributes:
10+
value: |
11+
**Thanks for taking the time to fill out this bug report!**
12+
13+
- type: checkboxes
14+
attributes:
15+
label: Is there an existing issue for this?
16+
description: Search for existing issues for the bug you encountered.
17+
options:
18+
- label: I have searched, and found nothing match my bug.
19+
required: true
20+
21+
- type: textarea
22+
id: what-happened
23+
attributes:
24+
label: What happened?
25+
description: |
26+
What did you do, and what did you encounter?
27+
It is best to include a screenshot, gif or screen recording of your issue.
28+
placeholder: Tell us what you see!
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: what-expected
34+
attributes:
35+
label: Expected result?
36+
description: Briefly describe your expected results.
37+
placeholder: Describe what you want!
38+
validations:
39+
required: true
40+
41+
- type: textarea
42+
attributes:
43+
label: Steps to Reproduce
44+
description: |
45+
Please describe exactly how to reproduce the bug.
46+
value: |
47+
<details>
48+
<summary>Steps</summary>
49+
50+
1.
51+
2.
52+
3.
53+
54+
</details>
55+
validations:
56+
required: true
57+
58+
- type: input
59+
id: version
60+
attributes:
61+
label: Your package version
62+
description: Use `pip show <package-name>` to get the version.
63+
validations:
64+
required: true
65+
66+
- type: dropdown
67+
id: os
68+
attributes:
69+
label: Operating System?
70+
multiple: true
71+
options:
72+
- Windows
73+
- Linux
74+
- macOS
75+
76+
- type: textarea
77+
id: appendix
78+
attributes:
79+
label: Appendix
80+
description: Any addition information helping to resolve this issue is welcome.
81+
value: |
82+
<details>
83+
<summary>Details</summary>
84+
85+
1.
86+
2.
87+
3.
88+
89+
</details>
90+
validations:
91+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
blank_issues_enabled: false
2+
# contact_links:
3+
# - name: GitHub Community Support
4+
# url: https://github.com/orgs/community/discussions
5+
# about: Please ask and answer questions here.
6+
7+
# - name: GitHub Security Bug Bounty
8+
# url: https://bounty.github.com/
9+
# about: Please report security vulnerabilities here.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Feature Request
2+
description: File a feature request.
3+
title: "[🧩 Feature Request]: "
4+
labels: ["enhancement", "triage"]
5+
6+
body:
7+
8+
- type: markdown
9+
attributes:
10+
value: |
11+
> **Thanks for taking the time to submit a feature request!**
12+
13+
- type: textarea
14+
id: feature-description
15+
attributes:
16+
label: Feature Description
17+
description: |
18+
Please describe the feature you would like to see implemented.
19+
placeholder: Tell us what you want!
20+
validations:
21+
required: true
22+
23+
- type: textarea
24+
id: use-case
25+
attributes:
26+
label: Use Case
27+
description: |
28+
Describe a use case or scenario where this feature would be beneficial.
29+
placeholder: Describe the use case!
30+
validations:
31+
required: true
32+
33+
- type: textarea
34+
attributes:
35+
label: Alternatives
36+
description: |
37+
Are there any existing solutions or alternatives to the feature you are requesting?
38+
placeholder: List alternatives!
39+
validations:
40+
required: true
41+
42+
- type: dropdown
43+
id: priority
44+
attributes:
45+
label: Priority
46+
description: |
47+
How important is this feature to you and the project?
48+
options:
49+
- High
50+
- Medium
51+
- Low
52+
default: 2
53+
validations:
54+
required: true
55+
56+
- type: dropdown
57+
id: category
58+
attributes:
59+
label: Category
60+
description: |
61+
Choose the category that best fits this feature request.
62+
options:
63+
- UI/UX
64+
- Functionality
65+
- Performance
66+
- Documentation
67+
- Other
68+
validations:
69+
required: true
70+
71+
- type: textarea
72+
id: appendix
73+
attributes:
74+
label: Appendix
75+
description: Any additional information or context that would help in evaluating this feature request.
76+
placeholder: Additional details!
77+
validations:
78+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
## 📋 Summary
2+
3+
> [!IMPORTANT]
4+
> - [ ] This PR fixes an issue. [Link]() <!--Link to related issues if applicable -->
5+
> - [ ] This PR adds something new.
6+
> - [ ] This PR is **not** a code change (e.g. `README`, typos, ...)
7+
> - [ ] This PR has been tested.
8+
9+
<!-- What is this pull request for? Does it fix any issues? -->
10+
11+
## 📝 Changes
12+
13+
<!-- Describe what you change and what the purpose in this pull request. -->
14+
15+
<details>
16+
<summary>Details</summary>
17+
18+
- `file1`: modify xxx, in order to achieve a xxx result.
19+
- `file2`: add xxx, in order to fix xxx.
20+
21+
</details>
22+
23+
## 🛠️ How to test
24+
25+
<!-- Describe your testing approach and results. Replace the example below-->
26+
27+
<details>
28+
<summary>Example</summary>
29+
30+
For manual testing:
31+
- Install the library in a fresh virtual environment.
32+
- Import main library functions/classes and perform basic operations.
33+
- Test configuration options by setting different values and verify library behavior changes.
34+
- If library interacts with external services, mock them and ensure it handles errors gracefully.
35+
36+
For automated testing:
37+
- We use `pytest` for testing. Test suite has unit tests for functions and methods in library.
38+
- Integration tests are in place to check interaction between library components.
39+
- We run tests on `GitHub Actions`. Ensures every commit triggers test suite, reports failures immediately.
40+
- Performance tests are conducted periodically to measure the efficiency of critical functions.
41+
42+
</details>
43+
44+
45+
## 📷 Screenshots/Examples (if needed):
46+
47+
<!-- Add screenshots or examples to illustrate the changes if needed. -->

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
1+
# v1.3.0
2+
3+
![](https://img.shields.io/badge/Version-v1.3.0-green)
4+
5+
## 🌟 Add
6+
7+
1. `.github/CONTRIBUTING.md` : guide other to make contribution to your project.
8+
9+
2. `.github/ISSUE_TEMPLATE` : standardize the format of `issue` reporting. Composed of `bug_report.yml`, `feature_request.yml` and `config.yml`.
10+
11+
3. `.github/PULL_REQUEST_TEMPLATE.md` : standardize the format of `Pull Request`.
12+
13+
---
14+
115
# v1.2.3
216

317
![](https://img.shields.io/badge/Version-v1.2.3-green)

‎README.md‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
## 📦 A Project Template for Self-developed Python Package
22

3-
[![Package Version](https://img.shields.io/badge/Version-v1.2.3-green)](https://github.com/Ahzyuan/Python-package-template/releases/tag/v1.2.3)
3+
[![Package Version](https://img.shields.io/badge/Version-v1.3.0-green)](https://github.com/Ahzyuan/Python-package-template/releases/tag/v1.3.0)
44
[![License](https://img.shields.io/badge/License-MIT-khaki)](https://opensource.org/license/MIT)
55
![Pypi Template](https://img.shields.io/badge/PyPI-Package_pattern-yellow?logo=pypi&labelColor=%23FAFAFA)
66

@@ -20,7 +20,10 @@ This repo provides an 𝐨𝐮𝐭-𝐨𝐟-𝐭𝐡𝐞-𝐛𝐨𝐱 𝐩𝐫
2020
<details>
2121
<summary>𝐀 𝐮𝐬𝐞𝐟𝐮𝐥, 𝐨𝐮𝐭-𝐨𝐟-𝐭𝐡𝐞-𝐛𝐨𝐱 𝐩𝐫𝐨𝐣𝐞𝐜𝐭 𝐬𝐭𝐫𝐮𝐜𝐭𝐮𝐫𝐞 that complies with software engineering specifications.</summary>
2222

23-
```
23+
```plaix-txt
24+
# Note:
25+
# the directory structure below neglects the `.github` dir and `.gitignore` file
26+
2427
Python-package-template/
2528
├── tests/ # Storage unit test code
2629
│ └── README.md # Instructions for testing your code
@@ -31,7 +34,6 @@ Python-package-template/
3134
├── package-name/ # Store project code
3235
│ ├── core.py # Core code
3336
│ └── __init__.py # Package initialization file, defining copyright, version,and other information
34-
├── .gitignore # File ignored by Git
3537
├── LICENSE # Project license
3638
├── MANIFEST.in # Describe the files included or not included in buildpackage
3739
├── CHANGELOG.md # Project changelog
@@ -106,6 +108,9 @@ We use the wonderful Python linter and formatter [`Ruff`](https://github.com/ast
106108
> <summary>𝘯𝘰𝘸 𝘺𝘰𝘶𝘳 𝘱𝘳𝘰𝘫𝘦𝘤𝘵 𝘴𝘵𝘳𝘶𝘤𝘵𝘶𝘳𝘦 𝘴𝘩𝘰𝘶𝘭𝘥 𝘣𝘦 𝘭𝘪𝘬𝘦 𝘵𝘩𝘪𝘴</summary>
107109
>
108110
> ```
111+
> # Note:
112+
> # the directory structure below neglects the `.github` dir and `.gitignore` file
113+
>
109114
> MYPROJECT/
110115
> ├── tests/
111116
> │ └── README.md
@@ -115,8 +120,7 @@ We use the wonderful Python linter and formatter [`Ruff`](https://github.com/ast
115120
> │ └── demo.ipynb
116121
> ├── my-project/
117122
> │ ├── core.py
118-
> │ └── __init__.py
119-
> ├── .gitignore
123+
> │ └── __init__.py
120124
> ├── LICENSE
121125
> ├── MANIFEST.in
122126
> ├── CHANGELOG.md
@@ -476,6 +480,27 @@ If you want to close the server, using `kill -9 "$(pgrep pypi-server)"`.
476480
477481
</details>
478482
483+
## 🗃 Project Management
484+
485+
> This section emphasizes the effective management of your project on `GitHub`.
486+
487+
The following files are helpful for **standardizing the process of `issue` reporting and `Pull Request`**.
488+
489+
They are preset in this template repo, you can change them according to your needs
490+
491+
1. [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) : guide other to make contribution to your project. To change it, refer to [link](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors).
492+
493+
2. [`.github/ISSUE_TEMPLATE`](.github/ISSUE_TEMPLATE) : standardize the format of `issue` reporting. Composed of
494+
> Tips: Open the [`Issue page`](https://github.com/Ahzyuan/Python-package-template/issues/new/choose) to see what the template looks like.
495+
496+
- [`bug_report.yml`](.github/ISSUE_TEMPLATE/bug_report.yml): template for reporting bugs.
497+
- [`feature_request.yml`](.github/ISSUE_TEMPLATE/feature_request.yml): template for requesting new features.
498+
- [`config.yml`](.github/ISSUE_TEMPLATE/config.yml): A template selector to control others' ability to initiate an `issue` without using a template.
499+
500+
If you are to change it, refer to [link1](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository), [link2](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) and [link3](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema).
501+
502+
1. [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) : standardize the format of `Pull Request`. To change it, refer to [link](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository).
503+
479504
## 📑 To Do
480505

481506
- [x] Add full pipeline of package development, from project preparation to maintaining.

0 commit comments

Comments
 (0)