Skip to content

Commit 694a311

Browse files
Udhay-AdithyaUdhay-Adithya
committed
docs: add comprehensive documentation and contributing guidelines
1 parent 0109b8f commit 694a311

File tree

6 files changed

+835
-130
lines changed

6 files changed

+835
-130
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ src/__pycache__/
44
src/mark_test.py
55
src/parsers/__pycache__/
66
src/utils/__pycache__/
7-
test.py
7+
test.py
8+
__pycache__/

‎CODE_OF_CONDUCT.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
[udhayxd@gmail.com](mailto:udhayxd@gmail.com).
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
For answers to common questions about this code of conduct, see the FAQ at
122+
[https://www.contributor-covenant.org/faq][faq]. Translations are available
123+
at [https://www.contributor-covenant.org/translations][translations].
124+
125+
[homepage]: https://www.contributor-covenant.org
126+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
127+
[faq]: https://www.contributor-covenant.org/faq
128+
[translations]: https://www.contributor-covenant.org/translations

‎CONTRIBUTING.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Contributing to VIT-AP VTOP API
2+
3+
First off, thank you for considering contributing to the VIT-AP VTOP API! Your help is essential for keeping it great.
4+
5+
This document provides guidelines for contributing to this project. Please read it carefully to ensure a smooth and effective contribution process.
6+
7+
## Table of Contents
8+
- [Code of Conduct](#code-of-conduct)
9+
- [How Can I Contribute?](#how-can-i-contribute)
10+
- [Reporting Bugs](#reporting-bugs)
11+
- [Suggesting Enhancements](#suggesting-enhancements)
12+
- [Pull Requests](#pull-requests)
13+
- [Development Setup](#development-setup)
14+
- [Coding Guidelines](#coding-guidelines)
15+
- [Python Style Guide](#python-style-guide)
16+
- [Commit Messages](#commit-messages)
17+
- [Testing](#testing)
18+
- [Documentation](#documentation)
19+
- [Community](#community)
20+
21+
## Code of Conduct
22+
This project and everyone participating in it is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
23+
24+
## How Can I Contribute?
25+
26+
### Reporting Bugs
27+
If you find a bug, please ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/Udhay-Adithya/vit_ap_vtop_api/issues).
28+
29+
If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Udhay-Adithya/vit_ap_vtop_api/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample or an executable test case** demonstrating the expected behavior that is not occurring.
30+
31+
Provide the following information:
32+
- Your operating system name and version.
33+
- Python version.
34+
- Any details about your local setup that might be helpful in troubleshooting.
35+
- Detailed steps to reproduce the bug.
36+
37+
### Suggesting Enhancements
38+
If you have an idea for an enhancement, please first discuss the change you wish to make via a GitHub issue before making a change.
39+
40+
Provide the following information:
41+
- A clear and descriptive title.
42+
- A detailed description of the proposed enhancement.
43+
- The motivation or use case for the enhancement.
44+
- Any potential drawbacks or alternative solutions.
45+
46+
### Pull Requests
47+
Pull Requests (PRs) are the primary way to contribute code to this project.
48+
49+
1. **Fork the repository**:
50+
51+
Click the "Fork" button at the top right of the [repository page](https://github.com/Udhay-Adithya/vit_ap_vtop_api).
52+
53+
54+
2. **Clone your fork**:
55+
56+
57+
```bash
58+
git clone https://github.com/Udhay-Adithya/vit_ap_vtop_api.git
59+
```
60+
61+
62+
3. **Create a new branch**:
63+
64+
65+
```bash
66+
# For new-features
67+
git checkout -b feature/your-feature-name
68+
# For bug-fixes
69+
bugfix/issue-number-description
70+
```
71+
72+
73+
4. **Set up your development environment**: Follow the [Development Setup](#development-setup) instructions.
74+
5. **Make your changes**: Implement your feature or bug fix.
75+
6. **Follow Coding Guidelines**: Ensure your code adheres to the [Coding Guidelines](#coding-guidelines).
76+
7. **Add tests**: Write unit tests for your changes.
77+
8. **Commit your changes**: Use clear and descriptive [Commit Messages](#commit-messages).
78+
9. **Push to your fork**: `git push origin feature/your-feature-name`.
79+
10. **Open a Pull Request**: Go to the original repository and open a PR from your forked branch to the `main` branch of the original repository.
80+
- Provide a clear title and description for your PR, linking to any relevant issues.
81+
- Ensure all automated checks (linters, tests) pass.
82+
83+
Project maintainers will review your PR and may request changes. Please be responsive to feedback.
84+
85+
## Development Setup
86+
To set up the project for local development:
87+
88+
1. **Clone the repository** (if you haven't already forked and cloned):
89+
```bash
90+
git clone https://github.com/Udhay-Adithya/.git
91+
cd vit_ap_vtop_api
92+
```
93+
2. **Create a virtual environment** (recommended):
94+
```bash
95+
python -m venv venv
96+
source venv/bin/activate # On Windows use `venv\Scripts\activate`
97+
```
98+
3. **Install dependencies**:
99+
```bash
100+
pip install -r requirements.txt
101+
```
102+
You might also want to install development dependencies if a `requirements-dev.txt` file is available:
103+
```bash
104+
# pip install -r requirements-dev.txt
105+
```
106+
4. **Run the application**:
107+
```bash
108+
cd src
109+
uvicorn main:app --reload
110+
```
111+
112+
## Coding Guidelines
113+
114+
### Python Style Guide
115+
- Follow [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/).
116+
- Use a linter like Flake8 or Pylint to check your code.
117+
- Keep functions and methods small and focused on a single task.
118+
- Add comments to explain complex logic or non-obvious code.
119+
- Use type hints where appropriate.
120+
121+
### Commit Messages
122+
- Use the present tense ("Add feature" not "Added feature").
123+
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
124+
- Limit the first line to 72 characters or less.
125+
- Reference issues and PRs liberally.
126+
- Consider using [Conventional Commits](https://www.conventionalcommits.org/) for more structured commit messages, e.g.:
127+
- `feat: add new endpoint for course registration`
128+
- `fix: resolve issue with captcha parsing`
129+
- `docs: update README with new setup instructions`
130+
- `refactor: improve performance of attendance fetching`
131+
- `test: add unit tests for profile parser`
132+
133+
## Testing
134+
- Write unit tests for new features and bug fixes.
135+
- Ensure all existing tests pass before submitting a PR.
136+
- Tests are typically located in a `tests/` directory (though not explicitly shown in the provided project structure, it's a best practice).
137+
- Use a testing framework like `pytest` or Python's built-in `unittest`.
138+
139+
## Documentation
140+
- Keep the `README.md` and other documentation files up-to-date with your changes.
141+
- If you add new features or change existing ones, update the relevant sections of the documentation.
142+
- For API changes, ensure the endpoint descriptions, request/response formats, and examples are accurate.
143+
144+
## Community
145+
Join the discussion! If you have questions or want to discuss ideas, feel free to open an issue or participate in existing discussions.
146+
147+
Thank you for contributing!

0 commit comments

Comments
 (0)