Skip to content

Commit a7018a4

Browse files
legendof-seldalegendof-selda
authored
Chore/contributing (#5)
* chore: add contributing.md * ci: add ensure clean workflow * ci: poetry cli changed for check * lint(evaluation): format black * chore: add .python-version for ci * lint(evaluation): unnecessary imports and stuff
1 parent 5faff8b commit a7018a4

5 files changed

Lines changed: 266 additions & 249 deletions

File tree

‎.github/workflows/ensure_clean.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Ensure files are formatted.
2+
3+
on: [workflow_dispatch, push]
4+
5+
jobs:
6+
ensure_formatted:
7+
runs-on: ubuntu-latest
8+
9+
steps:
10+
- uses: actions/checkout@v4
11+
12+
- name: Setup Poetry
13+
uses: Gr1N/setup-poetry@v9
14+
with:
15+
poetry-version: ${{ env.POETRY_VERSION }}
16+
17+
- name: Install Python
18+
id: install-python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version-file: .python-version
22+
cache: "poetry"
23+
24+
- uses: actions/cache@v4
25+
with:
26+
key: style-${{ hashFiles('**/poetry.lock') }}
27+
path: ./.venv
28+
restore-keys: |
29+
style-
30+
31+
- name: Install Python Dependencies
32+
run: |
33+
poetry install --sync
34+
35+
- name: Normalize all files
36+
run: |
37+
source .venv/bin/activate
38+
git add --renormalize .
39+
40+
- name: Format all python files
41+
run: |
42+
source .venv/bin/activate
43+
black `git ls-files '*.py'`
44+
isort `git ls-files '*.py'`
45+
46+
- name: Make sure poetry.lock is in sync
47+
run: |
48+
poetry check --lock
49+
50+
- name: Check that no files were changed
51+
run: |
52+
source .venv/bin/activate
53+
git --no-pager diff
54+
git status --porcelain
55+
[ -z "$(git status --porcelain)" ]

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.12.7

‎CONTRIBUTING.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Contributing Guide
2+
3+
We welcome all types of contributions to Supermat, including bug reports, feature requests, code improvements, documentation updates, and tests. Please follow the guidelines below to help us maintain a high-quality, collaborative project.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Contributing Guide](#contributing-guide)
10+
- [Table of Contents](#table-of-contents)
11+
- [1. Development Setup](#1-development-setup)
12+
- [2. Branch \& Commit Naming Conventions](#2-branch--commit-naming-conventions)
13+
- [Branch Naming](#branch-naming)
14+
- [Commit Messages](#commit-messages)
15+
- [3. Issue Reporting Guidelines](#3-issue-reporting-guidelines)
16+
- [4. Testing](#4-testing)
17+
- [5. Documentation](#5-documentation)
18+
- [6. Code Formatting](#6-code-formatting)
19+
- [7. Code of Conduct](#7-code-of-conduct)
20+
- [8. Final Steps](#8-final-steps)
21+
22+
---
23+
24+
## 1. Development Setup
25+
26+
To set up your local development environment:
27+
28+
1. **Clone the Repository**
29+
30+
```bash
31+
git clone https://github.com/SupermatAI/supermat.git
32+
cd supermat
33+
```
34+
35+
2. **Install Dependencies with Poetry**
36+
Ensure you have [Python Poetry](https://python-poetry.org/) installed. Then run:
37+
38+
```bash
39+
poetry install --with=dev,docs,frontend --all-extras
40+
```
41+
42+
3. **Run the Application**
43+
To see Supermat in action via the Gradio interface, run:
44+
45+
```bash
46+
python -m supermat.gradio
47+
```
48+
49+
4. **Virtual Environment (Optional)**
50+
Poetry automatically handles virtual environments. If needed, refer to Poetry’s documentation for managing virtual environments.
51+
52+
---
53+
54+
## 2. Branch & Commit Naming Conventions
55+
56+
We follow [Conventional Commits](https://www.conventionalcommits.org/) and semantic versioning principles for clarity and automation. This ensures that commit messages also help determine version bumps (e.g., breaking changes lead to major version increments, features to minor, fixes to patch).
57+
58+
### Branch Naming
59+
60+
Branches should be named in the following format:
61+
62+
```
63+
<type>/<issue-number>-<short-description>
64+
```
65+
66+
- **`<type>`:** One of the following:
67+
- `feat` (new feature)
68+
- `fix` (bug fix)
69+
- `docs` (documentation changes)
70+
- `style` (formatting, no functional changes)
71+
- `refactor` (code refactoring)
72+
- `test` (adding or updating tests)
73+
- `chore` (maintenance tasks)
74+
- **`<issue-number>`:** Reference the related issue (if applicable).
75+
- **`<short-description>`:** A brief, hyphen-separated summary.
76+
77+
**Examples:**
78+
79+
- `feat/123-add-user-auth`
80+
- `fix/456-correct-api-endpoint`
81+
- `docs/789-update-readme`
82+
83+
### Commit Messages
84+
85+
Commit messages should follow this structure:
86+
87+
```
88+
<type>(<scope>): <description>
89+
```
90+
91+
- **`<type>`:** Same as above (e.g., `feat`, `fix`).
92+
- **`<scope>`:** (Optional) The module or area affected.
93+
- **`<description>`:** A concise summary in the imperative mood (e.g., “add,” “fix,” “update”).
94+
95+
**Examples:**
96+
97+
- `feat(auth): add JWT-based user authentication`
98+
- `fix(api): correct endpoint URL for data retrieval`
99+
- `docs: update installation instructions`
100+
101+
For breaking changes, either append an exclamation mark after the type or include a `BREAKING CHANGE:` footer:
102+
103+
- `feat!: overhaul authentication system`
104+
- Or:
105+
106+
```markdown
107+
feat(auth): update user authentication
108+
109+
BREAKING CHANGE: The authentication API has changed; please update your integration accordingly.
110+
```
111+
112+
---
113+
114+
## 3. Issue Reporting Guidelines
115+
116+
When opening a new issue, please include the following information:
117+
118+
- **Title:** A clear and descriptive title summarizing the problem.
119+
- **Description:** A detailed explanation of the issue.
120+
- **Steps to Reproduce:** Provide step-by-step instructions that allow us to reproduce the problem.
121+
- **Expected vs. Actual Behavior:** Describe what you expected to happen and what actually occurred.
122+
- **Environment Details:** Include OS, Python version, and any other relevant setup details.
123+
- **Screenshots/Logs:** Attach screenshots or error logs if available.
124+
125+
---
126+
127+
## 4. Testing
128+
129+
We use [pytest](https://docs.pytest.org/) for running our test suite.
130+
131+
- **Run Tests Locally:**
132+
133+
Simply execute:
134+
135+
```bash
136+
pytest
137+
```
138+
139+
- **Before Submitting a PR:**
140+
Ensure that all tests pass.
141+
142+
---
143+
144+
## 5. Documentation
145+
146+
Our documentation is built with [MkDocs](https://www.mkdocs.org/).
147+
148+
- **Viewing Documentation Locally:**
149+
150+
Run:
151+
152+
```bash
153+
mkdocs serve
154+
```
155+
156+
This command will start a local server so you can preview the docs as you work on them.
157+
- **Contributing Changes:**
158+
Please follow the structure in the `docs/` folder and update `SUMMARY.md` if you add new pages.
159+
160+
---
161+
162+
## 6. Code Formatting
163+
164+
We use [black](https://black.readthedocs.io/) and [isort](https://pycqa.github.io/isort/) to enforce a consistent code style. Configuration is managed in `pyproject.toml`.
165+
166+
- **Format Code with Black:**
167+
168+
```bash
169+
black .
170+
```
171+
172+
- **Sort Imports with isort:**
173+
174+
```bash
175+
isort .
176+
```
177+
178+
Please run these tools on your changes before submitting a pull request.
179+
180+
---
181+
182+
## 7. Code of Conduct
183+
184+
To maintain a friendly and inclusive environment, we ask all contributors to follow our Code of Conduct. We are adopting the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) as our Code of Conduct.
185+
186+
- **Location:**
187+
A copy of the Code of Conduct should be added to the repository as `CODE_OF_CONDUCT.md`.
188+
- **Expectations:**
189+
All contributors are expected to treat others with respect and to refrain from harassment or exclusionary behavior.
190+
- **Reporting:**
191+
If you experience or witness any violations, please report them to the project maintainers via the contact details provided in the Code of Conduct.
192+
193+
---
194+
195+
## 8. Final Steps
196+
197+
- **Pull Requests:**
198+
- Ensure that your branch name and commit messages adhere to the guidelines above.
199+
- Run all tests and format your code before submission.
200+
- **Review Process:**
201+
Your pull request will undergo review and feedback. Please address any requested changes promptly.
202+
- **Questions:**
203+
If you have any questions about contributing, feel free to open an issue or join our discussions.
204+
205+
Thank you for contributing to Supermat and helping us build a better project!
206+
207+
---

0 commit comments

Comments
 (0)