Add CI, tests, linting, and GitHub community files

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,154 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+national origin, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open and welcoming
+environment, and to demonstrate an empathy and regard for our fellow community
+members.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other community members
+* Being respectful of differing opinions, viewpoints, and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members who may be less experienced
+  than you
+* Being considerate of those who may not be as familiar with the conventions
+  used in our community
+* Learning from and being open to constructive feedback
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned with this Code of Conduct, and will communicate reasons for moderation
+decisions in a way that respects this community.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project leaders.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by contacting
+axect.tg@proton.me.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Harmful Conduct
+
+1.1. **Severity Levels**:
+
+* **1.0 - Minor**: Verbal or written comments that are considered slight but
+  hurtful or exclusionary. Minor offenses are those that are part of a pattern
+  of behavior or that would reasonably cause others to feel uncomfortable.
+
+* **2.0 - Significant**: Verbal or written comments that are considered
+  inappropriate, including those that are offensive or harmful. Significant
+  offenses include the presence of mild-to-moderate sexual content (including
+  references to sexual preferences or kinks, but not non-consensual sexual
+  content) that would make others uncomfortable.
+
+* **3.0 - Severe**: Actions that create hostile, threatening, or abusive
+  environments. Severe offenses include the presence of explicit sexual content,
+  hate speech, threats, or encouragement of self-harm.
+
+1.2. **Consequences**:
+
+* **Level 1.0**: A private note from a community leader expressing concern
+  regarding the behavior and inviting the individual to discuss what changes
+  they would like to make.
+
+* **Level 2.0**: A private note from a community leader with an explanation of
+  the unacceptable behavior, why it was unacceptable, and a request to
+  communicate more respectfully and considerately. A community leader may also
+  request the individual to stop engaging with the project until the issue is
+  resolved.
+
+* **Level 3.0**: Immediate, permanent exclusion from the project community and
+  any associated events, with zero tolerance for repetition.
+
+### 2. Unacceptable Conduct
+
+* **Sexual Content**: Comments or content that are explicitly sexual, including
+  detailed descriptions of sexual acts, genitalia, or sexual preferences and
+  kinks, even when consensual.
+
+* **Hate Speech**: Comments that target or dehumanize individuals based on
+  characteristics such as race, ethnicity, religion, disability, age, sex
+  characteristics, gender identity, sexual orientation, or other protected
+  status.
+
+* **Harassment**: Verbal or written comments that are directed at an individual
+  with the intent to annoy, intimidate, or demean, or that would reasonably
+  cause a reasonable person to feel uncomfortable in the community.
+
+* **Personal Attacks**: Offensive comments or actions that target individuals
+  or groups based on their identity, beliefs, or affiliations.
+
+* **Targeted Offenses**: Conduct targeted at specific individuals or groups,
+  such as repeated harassment or exclusion of particular members of the
+  community.
+
+* **Unwelcome Physical Contact**: Any unwanted physical contact, including
+  touching, hugging, or other forms of physical contact that make someone
+  uncomfortable.
+
+* **Incitement to Harm**: Encouraging others to engage in harmful behavior,
+  including the promotion of illegal acts or violence.
+
+### 3. Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant version 2.1,
+available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+The enforcement guidelines have been adapted for our community's needs but
+maintain the spirit and intent of the original document.
+
+## Attribution
+
+This Code of Conduct and its enforcement guidelines are adapted from the
+Contributor Covenant version 2.1 (https://www.contributor-covenant.org) and
+the Python Software Foundation's Code of Conduct (https://www.python.org/psf/conduct/).
+
+## Contact
+
+For questions or concerns about this Code of Conduct, please contact
+axect.tg@proton.me.

.github/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to arXiv Explorer
+
+Thank you for your interest in contributing to arXiv Explorer! This guide will help you get started.
+
+## Prerequisites
+
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
+- **git**
+
+## Getting Started
+
+1. Fork the repository and clone your fork:
+
+   ```bash
+   git clone https://github.com/<your-username>/arXiv_explorer.git
+   cd arXiv_explorer
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+3. Verify the installation:
+
+   ```bash
+   uv run axp --help
+   ```
+
+## Development Workflow
+
+### Git Workflow
+
+This project follows **gitflow**:
+
+- **`main`** contains stable releases only.
+- **`dev`** is the active development branch.
+- All feature branches should be created from `dev`.
+- All pull requests should target `dev`.
+
+To start working on a change:
+
+```bash
+git checkout dev
+git pull origin dev
+git checkout -b feature/your-feature-name
+```
+
+### Code Style
+
+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:
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+```
+
+### Testing
+
+Run the full test suite with coverage:
+
+```bash
+uv run pytest --cov
+```
+
+To run a specific test file:
+
+```bash
+uv run pytest tests/test_recommendation.py
+```
+
+All new features should include tests. Aim to maintain or improve code coverage.
+
+### Commit Messages
+
+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").
+
+## Pull Request Process
+
+1. **Ensure all tests pass** before submitting your PR.
+2. **Ensure linting passes** with `uv run ruff check src/ tests/`.
+3. **Describe your changes** clearly in the PR description --- what was changed, why, and how to test it.
+4. **Target the `dev` branch** --- PRs to `main` will not be accepted unless they are release merges.
+5. **Keep PRs focused** --- one feature or fix per pull request makes review easier.
+
+## Reporting Issues
+
+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.
+
+## Questions?
+
+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

@@ -0,0 +1,84 @@
+name: Bug Report
+description: Report a bug in arXiv Explorer
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug. Please fill out the information below to help us investigate and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Run `uv run axp ...`
+        2. ...
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+      placeholder: Describe what you expected...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happened. Include any error messages or tracebacks.
+      placeholder: Describe what actually happened...
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version`.
+      placeholder: "e.g., 3.12.0"
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Your operating system and version.
+      placeholder: "e.g., Ubuntu 24.04, macOS 15.2, Windows 11"
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: arXiv Explorer Version
+      description: Output of `uv run axp --version` or the version in pyproject.toml.
+      placeholder: "e.g., 0.1.0"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem (logs, screenshots, configuration, etc.).
+      placeholder: Add any other context here...
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,45 @@
+name: Feature Request
+description: Suggest a new feature or improvement for arXiv Explorer
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a feature! Please provide as much detail as possible so we can evaluate and prioritize your request.
+
+  - type: textarea
+    id: problem-description
+    attributes:
+      label: Problem Description
+      description: Describe the problem or limitation you are experiencing. What is frustrating or missing?
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you would like to see. How should this feature work?
+      placeholder: Describe your ideal solution...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives-considered
+    attributes:
+      label: Alternatives Considered
+      description: Describe any alternative solutions or workarounds you have considered.
+      placeholder: List any alternatives you've thought about...
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or examples that help explain the feature request.
+      placeholder: Add any other context here...
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+<!-- Briefly describe the purpose of this pull request. What problem does it solve or what feature does it add? -->
+
+## Changes
+
+<!-- List the key changes made in this PR. -->
+
+-
+-
+-
+
+## Checklist
+
+- [ ] All tests pass (`uv run pytest --cov`)
+- [ ] Linting passes (`uv run ruff check src/ tests/`)
+- [ ] Documentation updated (if applicable)