Skip to content

Commit 97c01cd

Browse files
Axectclaude
Axect
and
claude
committed
Add GitHub community files for contributor experience
- CONTRIBUTING.md: dev setup, code style, testing, gitflow PR process - ISSUE_TEMPLATE/bug_report.yml: structured bug report form - ISSUE_TEMPLATE/feature_request.yml: feature request form - PULL_REQUEST_TEMPLATE.md: PR checklist (tests, lint, docs) - CODE_OF_CONDUCT.md: Contributor Covenant v2.1 - SECURITY.md: vulnerability reporting procedure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 7310fd2 commit 97c01cd

File tree

6 files changed

+406
-0
lines changed

6 files changed

+406
-0
lines changed

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
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+
national origin, race, religion, or sexual identity and orientation.
10+
11+
We pledge to act and interact in ways that contribute to an open and welcoming
12+
environment, and to demonstrate an empathy and regard for our fellow community
13+
members.
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 community members
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Gracefully accepting constructive criticism
23+
* Focusing on what is best for the community
24+
* Showing empathy towards other community members who may be less experienced
25+
than you
26+
* Being considerate of those who may not be as familiar with the conventions
27+
used in our community
28+
* Learning from and being open to constructive feedback
29+
30+
Examples of unacceptable behavior include:
31+
32+
* The use of sexualized language or imagery, and sexual attention or advances
33+
* Trolling, insulting or derogatory comments, and personal or political attacks
34+
* Public or private harassment
35+
* Publishing others' private information, such as a physical or electronic
36+
address, without explicit permission
37+
* Other conduct which could reasonably be considered inappropriate in a
38+
professional setting
39+
40+
## Our Responsibilities
41+
42+
Community leaders are responsible for clarifying and enforcing our standards
43+
of acceptable behavior and will take appropriate and fair corrective action in
44+
response to any instances of unacceptable behavior.
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 with this Code of Conduct, and will communicate reasons for moderation
49+
decisions in a way that respects this community.
50+
51+
## Scope
52+
53+
This Code of Conduct applies both within project spaces and in public spaces
54+
when an individual is representing the project or its community. Examples of
55+
representing a project or community include using an official project e-mail
56+
address, posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event. Representation of a project may be
58+
further defined and clarified by project leaders.
59+
60+
## Enforcement
61+
62+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
63+
reported to the community leaders responsible for enforcement by contacting
64+
axect.tg@proton.me.
65+
66+
All complaints will be reviewed and investigated promptly and fairly.
67+
68+
All community leaders are obligated to respect the privacy and security of the
69+
reporter of any incident.
70+
71+
## Enforcement Guidelines
72+
73+
Community leaders will follow these Community Impact Guidelines in determining
74+
the consequences for any action they deem in violation of this Code of Conduct:
75+
76+
### 1. Harmful Conduct
77+
78+
1.1. **Severity Levels**:
79+
80+
* **1.0 - Minor**: Verbal or written comments that are considered slight but
81+
hurtful or exclusionary. Minor offenses are those that are part of a pattern
82+
of behavior or that would reasonably cause others to feel uncomfortable.
83+
84+
* **2.0 - Significant**: Verbal or written comments that are considered
85+
inappropriate, including those that are offensive or harmful. Significant
86+
offenses include the presence of mild-to-moderate sexual content (including
87+
references to sexual preferences or kinks, but not non-consensual sexual
88+
content) that would make others uncomfortable.
89+
90+
* **3.0 - Severe**: Actions that create hostile, threatening, or abusive
91+
environments. Severe offenses include the presence of explicit sexual content,
92+
hate speech, threats, or encouragement of self-harm.
93+
94+
1.2. **Consequences**:
95+
96+
* **Level 1.0**: A private note from a community leader expressing concern
97+
regarding the behavior and inviting the individual to discuss what changes
98+
they would like to make.
99+
100+
* **Level 2.0**: A private note from a community leader with an explanation of
101+
the unacceptable behavior, why it was unacceptable, and a request to
102+
communicate more respectfully and considerately. A community leader may also
103+
request the individual to stop engaging with the project until the issue is
104+
resolved.
105+
106+
* **Level 3.0**: Immediate, permanent exclusion from the project community and
107+
any associated events, with zero tolerance for repetition.
108+
109+
### 2. Unacceptable Conduct
110+
111+
* **Sexual Content**: Comments or content that are explicitly sexual, including
112+
detailed descriptions of sexual acts, genitalia, or sexual preferences and
113+
kinks, even when consensual.
114+
115+
* **Hate Speech**: Comments that target or dehumanize individuals based on
116+
characteristics such as race, ethnicity, religion, disability, age, sex
117+
characteristics, gender identity, sexual orientation, or other protected
118+
status.
119+
120+
* **Harassment**: Verbal or written comments that are directed at an individual
121+
with the intent to annoy, intimidate, or demean, or that would reasonably
122+
cause a reasonable person to feel uncomfortable in the community.
123+
124+
* **Personal Attacks**: Offensive comments or actions that target individuals
125+
or groups based on their identity, beliefs, or affiliations.
126+
127+
* **Targeted Offenses**: Conduct targeted at specific individuals or groups,
128+
such as repeated harassment or exclusion of particular members of the
129+
community.
130+
131+
* **Unwelcome Physical Contact**: Any unwanted physical contact, including
132+
touching, hugging, or other forms of physical contact that make someone
133+
uncomfortable.
134+
135+
* **Incitement to Harm**: Encouraging others to engage in harmful behavior,
136+
including the promotion of illegal acts or violence.
137+
138+
### 3. Attribution
139+
140+
This Code of Conduct is adapted from the Contributor Covenant version 2.1,
141+
available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
142+
The enforcement guidelines have been adapted for our community's needs but
143+
maintain the spirit and intent of the original document.
144+
145+
## Attribution
146+
147+
This Code of Conduct and its enforcement guidelines are adapted from the
148+
Contributor Covenant version 2.1 (https://www.contributor-covenant.org) and
149+
the Python Software Foundation's Code of Conduct (https://www.python.org/psf/conduct/).
150+
151+
## Contact
152+
153+
For questions or concerns about this Code of Conduct, please contact
154+
axect.tg@proton.me.

‎.github/CONTRIBUTING.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Contributing to arXiv Explorer
2+
3+
Thank you for your interest in contributing to arXiv Explorer! This guide will help you get started.
4+
5+
## Prerequisites
6+
7+
- **Python 3.11+**
8+
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
9+
- **git**
10+
11+
## Getting Started
12+
13+
1. Fork the repository and clone your fork:
14+
15+
```bash
16+
git clone https://github.com/<your-username>/arXiv_explorer.git
17+
cd arXiv_explorer
18+
```
19+
20+
2. Install dependencies:
21+
22+
```bash
23+
uv sync
24+
```
25+
26+
3. Verify the installation:
27+
28+
```bash
29+
uv run axp --help
30+
```
31+
32+
## Development Workflow
33+
34+
### Git Workflow
35+
36+
This project follows **gitflow**:
37+
38+
- **`main`** contains stable releases only.
39+
- **`dev`** is the active development branch.
40+
- All feature branches should be created from `dev`.
41+
- All pull requests should target `dev`.
42+
43+
To start working on a change:
44+
45+
```bash
46+
git checkout dev
47+
git pull origin dev
48+
git checkout -b feature/your-feature-name
49+
```
50+
51+
### Code Style
52+
53+
We use [Ruff](https://docs.astral.sh/ruff/) for both linting and formatting. Before submitting a pull request, make sure your code passes both checks:
54+
55+
```bash
56+
uv run ruff check src/ tests/
57+
uv run ruff format src/ tests/
58+
```
59+
60+
### Testing
61+
62+
Run the full test suite with coverage:
63+
64+
```bash
65+
uv run pytest --cov
66+
```
67+
68+
To run a specific test file:
69+
70+
```bash
71+
uv run pytest tests/test_recommendation.py
72+
```
73+
74+
All new features should include tests. Aim to maintain or improve code coverage.
75+
76+
### Commit Messages
77+
78+
Write clear, descriptive commit messages that explain **why** the change was made, not just what was changed. Use the imperative mood in the subject line (e.g., "Add keyword weighting to recommendation engine" rather than "Added keyword weighting").
79+
80+
## Pull Request Process
81+
82+
1. **Ensure all tests pass** before submitting your PR.
83+
2. **Ensure linting passes** with `uv run ruff check src/ tests/`.
84+
3. **Describe your changes** clearly in the PR description --- what was changed, why, and how to test it.
85+
4. **Target the `dev` branch** --- PRs to `main` will not be accepted unless they are release merges.
86+
5. **Keep PRs focused** --- one feature or fix per pull request makes review easier.
87+
88+
## Reporting Issues
89+
90+
If you find a bug or have a feature request, please open an issue using the appropriate template. Provide as much detail as possible to help us understand and reproduce the problem.
91+
92+
## Questions?
93+
94+
If you have questions about contributing, feel free to open a discussion or reach out to the maintainer at axect.tg@proton.me.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Bug Report
2+
description: Report a bug in arXiv Explorer
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thank you for reporting a bug. Please fill out the information below to help us investigate and fix the issue.
10+
11+
- type: textarea
12+
id: description
13+
attributes:
14+
label: Description
15+
description: A clear and concise description of the bug.
16+
placeholder: Describe the bug...
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: steps-to-reproduce
22+
attributes:
23+
label: Steps to Reproduce
24+
description: Steps to reproduce the behavior.
25+
placeholder: |
26+
1. Run `uv run axp ...`
27+
2. ...
28+
3. See error
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: expected-behavior
34+
attributes:
35+
label: Expected Behavior
36+
description: What you expected to happen.
37+
placeholder: Describe what you expected...
38+
validations:
39+
required: true
40+
41+
- type: textarea
42+
id: actual-behavior
43+
attributes:
44+
label: Actual Behavior
45+
description: What actually happened. Include any error messages or tracebacks.
46+
placeholder: Describe what actually happened...
47+
validations:
48+
required: true
49+
50+
- type: input
51+
id: python-version
52+
attributes:
53+
label: Python Version
54+
description: Output of `python --version`.
55+
placeholder: "e.g., 3.12.0"
56+
validations:
57+
required: false
58+
59+
- type: input
60+
id: os
61+
attributes:
62+
label: Operating System
63+
description: Your operating system and version.
64+
placeholder: "e.g., Ubuntu 24.04, macOS 15.2, Windows 11"
65+
validations:
66+
required: false
67+
68+
- type: input
69+
id: version
70+
attributes:
71+
label: arXiv Explorer Version
72+
description: Output of `uv run axp --version` or the version in pyproject.toml.
73+
placeholder: "e.g., 0.1.0"
74+
validations:
75+
required: false
76+
77+
- type: textarea
78+
id: additional-context
79+
attributes:
80+
label: Additional Context
81+
description: Any other context about the problem (logs, screenshots, configuration, etc.).
82+
placeholder: Add any other context here...
83+
validations:
84+
required: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement for arXiv Explorer
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thank you for suggesting a feature! Please provide as much detail as possible so we can evaluate and prioritize your request.
10+
11+
- type: textarea
12+
id: problem-description
13+
attributes:
14+
label: Problem Description
15+
description: Describe the problem or limitation you are experiencing. What is frustrating or missing?
16+
placeholder: "I'm always frustrated when..."
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: proposed-solution
22+
attributes:
23+
label: Proposed Solution
24+
description: Describe the solution you would like to see. How should this feature work?
25+
placeholder: Describe your ideal solution...
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: alternatives-considered
31+
attributes:
32+
label: Alternatives Considered
33+
description: Describe any alternative solutions or workarounds you have considered.
34+
placeholder: List any alternatives you've thought about...
35+
validations:
36+
required: false
37+
38+
- type: textarea
39+
id: additional-context
40+
attributes:
41+
label: Additional Context
42+
description: Any other context, screenshots, or examples that help explain the feature request.
43+
placeholder: Add any other context here...
44+
validations:
45+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Summary
2+
3+
<!-- Briefly describe the purpose of this pull request. What problem does it solve or what feature does it add? -->
4+
5+
## Changes
6+
7+
<!-- List the key changes made in this PR. -->
8+
9+
-
10+
-
11+
-
12+
13+
## Checklist
14+
15+
- [ ] All tests pass (`uv run pytest --cov`)
16+
- [ ] Linting passes (`uv run ruff check src/ tests/`)
17+
- [ ] Documentation updated (if applicable)

0 commit comments

Comments
 (0)