|
1 |
| -# Open-Source Research Project in Python: A Template |
2 |
| - |
3 |
| -[](https://www.python.org/downloads/release/python-3109/) |
4 |
| -[](https://pre-commit.com/) |
5 |
| -<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a> |
6 |
| -[](https://mypy-lang.org/) |
7 |
| -[](https://beartype.readthedocs.io) |
8 |
| -[]() |
9 |
| - |
10 |
| -> [!NOTE] |
11 |
| -> This repo is continously updating with more tools. Any contribution is welcome. |
12 |
| -
|
13 |
| -## ✨ Motivation |
14 |
| - |
15 |
| -To ensure high standards in engineering projects, we offer a standardized template specifically designed for open-source Python research projects. This template is an excellent choice if you: |
16 |
| - |
17 |
| -1. Want to facilitate seamless collaboration and extension of your project by other researchers. |
18 |
| -2. Aim to bridge communication gaps among collaborators effectively. |
19 |
| -3. Seek to make rapid iterations with assurance that small code modifications won’t disrupt the overall project. |
20 |
| -4. Wish to reduce the frequency of frustrating runtime errors during experiments. |
21 |
| - |
22 |
| -## 🔨 Continuous Integration (CI) Workflow |
23 |
| - |
24 |
| -Here's a clearer and more straightforward guideline of the steps for working with your codebase. If working in a small group or working on a simple project, some of the steps can be skipped. |
25 |
| - |
26 |
| -1. **Create Issue** |
27 |
| - |
28 |
| - Before starting, open a new issue in the repository detailing what you plan to implement. Assign the issue to yourself. |
29 |
| - |
30 |
| -2. **Sync Repo** |
31 |
| - |
32 |
| - Update your local repository to match the latest version of the remote repository. |
33 |
| - |
34 |
| -3. **Create Branch** |
35 |
| - |
36 |
| - Create a new branch for your task. Name it appropriately based on the type of task, such as `feature/feature-name`, `bug/bug-name`, or `exp/exp-name`. |
37 |
| - |
38 |
| -4. **Implement Code** |
39 |
| - |
40 |
| - Work on your task and make necessary changes to the codebase. |
41 |
| - |
42 |
| -5. **Test Locally** |
43 |
| - |
44 |
| - Run tests using tools like mypy, pytest, and pre-commit. Ensure all tests pass before proceeding. |
45 |
| - |
46 |
| -6. **Change Commit** |
47 |
| - |
48 |
| - Add and commit your changes to the branch, then push the branch to the repository. |
49 |
| - |
50 |
| -7. **Create PR** |
51 |
| - |
52 |
| - Open a Pull Request (PR) for the branch you've pushed. |
53 |
| - |
54 |
| -8. **Link PR to Issue** |
55 |
| - |
56 |
| - In your PR, include "Closes #ISSUE_NUM" to link it to the original issue. |
57 |
| - |
58 |
| -9. **Pass Continuous Integration** |
59 |
| - |
60 |
| - Ensure all GitHub Actions checks pass. If they fail, revise your code based on the errors reported. |
61 |
| - |
62 |
| -10. **Review PR Checklist** |
63 |
| - |
64 |
| - Verify that all items in the PR checklist are completed, such as updating documentation or adding package requirements. |
65 |
| - |
66 |
| -11. **Ask for Code Review** |
67 |
| - |
68 |
| - Invite a colleague to review your PR. One approved, Use the "Squash and Merge" option to merge your PR, ensuring a clean commit history. |
69 |
| - |
70 |
| -12. **Troubleshooting** |
71 |
| - |
72 |
| - If you break down the commit history or main branch, contact the repository owner for assistance with `rebase` or other needed actions. |
73 |
| - |
74 |
| -## 💼 Template Structure |
75 |
| - |
76 |
| -The current project template supports the final package release of our codebase. |
77 |
| - |
78 |
| -``` |
79 |
| -Template/ |
80 |
| -│ |
81 |
| -├── .github/ # Contains GitHub related files like workflows |
82 |
| -├── docs/ # Documentation for the project |
83 |
| -├── src/ # Main package directory |
84 |
| -├── stubs/ # Type stubs for static typing (for mypy strict mode) |
85 |
| -├── tests/ # Test scripts and resources |
86 |
| -│ |
87 |
| -├── .gitignore # Specifies untracked files to ignore |
88 |
| -├── .pre-commit-config.yaml # Configurations for pre-commit hooks |
89 |
| -├── poetry.lock # Lock file generated by poetry for dependencies |
90 |
| -├── pyproject.toml # Project metadata and tool configurations |
91 |
| -``` |
92 |
| - |
93 |
| -## ❓ Issue & Pull Request |
94 |
| - |
95 |
| -An issue typically describes a new feature (`feature`), fixing an old bug (`bug`), launching a group of experiments (`exp`), or refactoring part of the code (`refactor`). Using different issue templates for different issues. |
96 |
| - |
97 |
| -A PR typically implements the content mentioned in one issue. |
98 |
| - |
99 |
| -Notice about the development: |
100 |
| - |
101 |
| -1. When creating an issue, assign the responsible member for fixing that if possible |
102 |
| -2. When creating a PR, make sure you uses `feature/feature-name`, `bug/bug-name`, `exp/exp-name` for its branch |
103 |
| -3. When finishing one PR, make sure all the github action is passed and all the checks are done. |
104 |
| -4. When merging one PR, make sure using `squash and merge` instead of `merge a pull request`. |
105 |
| -5. Avoid making any direct commit to the `main` branch and try to avoid any `--force` push to any branch unless you are pretty sure about that. |
106 |
| - |
107 |
| -## 👷 Type Checking |
108 |
| - |
109 |
| -* Tools |
110 |
| - |
111 |
| - * static type checking (`mypy`) |
112 |
| - |
113 |
| - * dynamic type checking (`beartype`) |
114 |
| - |
115 |
| -* Guidelines |
116 |
| - * Run `mypy --strict ./` under the root of the current repo to test the static type. |
117 |
| - |
118 |
| -## 🏅️ Unit Testing |
119 |
| - |
120 |
| -* Tools |
121 |
| - * testing code components based on testing function (`pytest`) |
122 |
| - |
123 |
| -* Guidelines |
124 |
| - * Run `pytest` under the root of the current repo to check unit test results. |
125 |
| - |
126 |
| -## 🧐 Code Spell Checking |
127 |
| - |
128 |
| -* Tools |
129 |
| - * code spell checking (`codespell`) |
130 |
| - |
131 |
| -* Guidelines |
132 |
| - * Commonly need to ignore part of the files in the repository like `/data`. |
133 |
| - |
134 |
| -## 🪝 Pre-commit Hook |
135 |
| - |
136 |
| -* Tools |
137 |
| - |
138 |
| - * code formatting (`prettier`) |
139 |
| - |
140 |
| - * import package sorting (`isort`) |
141 |
| - |
142 |
| - * ipynb output clear (`nbstripout`) |
143 |
| - |
144 |
| - * code bug checking and formatting (`ruff`) |
145 |
| - |
146 |
| -* Guidelines |
147 |
| - |
148 |
| - * Run `python -m pip install pre-commit` to install `pre-commit` |
149 |
| - |
150 |
| - * Run `pre-commit install` to allow hooking pre-commit with any `git commit` commands. |
151 |
| - |
152 |
| -## 🧑💼 Dependency Management |
153 |
| - |
154 |
| -* Tools |
155 |
| - * We utilize `poetry` to support the dependency requirements. Dependency for different usage of the repo can be defined separately in `pyproject.toml`. |
156 |
| - |
157 |
| -* Guidelines |
158 |
| - |
159 |
| - * Run `pip install poetry` to finish the installation of poetry. |
160 |
| - |
161 |
| - * Create `conda environment` with a specified Python version |
162 |
| - |
163 |
| - * Run `poetry install` to install required dependencies. |
164 |
| - |
165 |
| -## ❤️ Contribution |
166 |
| - |
167 |
| -I welcome all kinds of contributions, e.g. adding more tools, better practices, and discussion on trade-offs. |
| 1 | +Tiny-Scientist |
0 commit comments