AdventureLog/CONTRIBUTING.md

# Contributing to AdventureLog

Thank you for your interest in contributing to **AdventureLog**!
AdventureLog is an open-source project built by and for people who love travel, exploration, and self-hosting. Contributions of all kinds are welcome — whether that’s fixing bugs, improving documentation, suggesting features, or writing code.

Our goal is to keep the project **open, welcoming, and organized** so that contributors can collaborate effectively and the codebase remains maintainable long-term.

This document explains how to contribute and the workflow we use.

---

# How Contributions Work

AdventureLog uses a structured workflow to keep development organized and to make it easier for contributors to collaborate.

All development follows this process:

```
Issue → Discussion → Approved → Ready → Development → Review → Merge
```

### 1. Open or Find an Issue

Before starting work, **please open an issue or find an existing one**.

Issues allow us to:

- discuss ideas before development begins
- coordinate work between contributors
- prevent duplicate efforts
- maintain a clear roadmap for the project

If you have an idea for a new feature or improvement, feel free to open an issue describing it.

---

### 2. Wait for Approval / Ready Status

Issues move through several stages:

**Backlog**
An idea or request that has not yet been reviewed.

**Needs Discussion**
The idea requires maintainer feedback or design discussion.

**Approved**
The concept has been accepted but may require planning.

**Ready**
The issue is ready for contributors to begin working on it.

⚠️ **Pull Requests should only be opened for issues marked `Ready`.**

This helps ensure contributors work on changes that are aligned with the project’s roadmap.

---

### 3. Start Working on the Issue

Once an issue is marked **Ready**, you can begin working on it.

If you plan to work on a larger issue, feel free to comment on the issue to let others know.

This helps prevent duplicate work.

---

### 4. Create a Pull Request

When your changes are ready, open a pull request targeting the **`development` branch**.

Your pull request must include a reference to the issue it resolves:

```
Closes #issue-number
```

This allows the project automation to track progress and update the project board.

Example PR description:

```
Closes #123

Adds support for exporting trips as GPX files.
```

---

### 5. Review Process

Once submitted, maintainers will review your pull request.

Reviews may include:

- code quality improvements
- consistency with the existing architecture
- performance considerations
- documentation updates

Please be open to feedback — reviews are intended to **improve the project and help contributors grow**.

---

### 6. Merge

After approval, your pull request will be merged into the **`development` branch**.

From there, it will eventually be included in the next release.

Thank you for helping improve AdventureLog!

---

# AI / LLM Assistance

Using AI tools (such as ChatGPT, Copilot, or other LLMs) **is allowed** when contributing to AdventureLog.

However, contributors are responsible for ensuring that generated code:

- is **correct and fully understood**
- follows the **project’s coding standards**
- integrates properly with the existing architecture
- does not introduce unnecessary complexity

AI-generated code that does not meet these standards may be rejected or the pull request may be closed.

Please review and clean up any AI-generated code before submitting it.

---

# Code Quality Expectations

To keep the project maintainable, all contributions should:

- follow the existing **code structure and architecture**
- use clear and readable code
- avoid unnecessary dependencies
- include documentation updates when relevant
- maintain compatibility with the existing system

AdventureLog currently includes:

- **Django** for the backend
- **SvelteKit** for the frontend
- **Docker-based deployments**

When contributing, please try to match the **style and patterns already used in the project**.

---

# Documentation Changes

If your changes affect:

- user workflows
- environment variables
- deployment setup
- API behavior
- configuration

please update the documentation in the:

```
/docs
```

folder accordingly.

Keeping documentation accurate is extremely important.

---

# Good Issues for New Contributors

If you are new to the project, look for issues labeled:

```
good first issue
help wanted
```

These are great starting points for new contributors.

---

# Code of Conduct

## Our Pledge

At AdventureLog, we are committed to creating a community that fosters adventure, exploration, and innovation.

We welcome contributors of all experience levels and backgrounds. Everyone should feel comfortable participating and sharing ideas.

---

## Our Standards

To maintain a positive environment, we encourage the following behaviors:

- **Inclusivity** — Use welcoming and inclusive language.
- **Respect** — Respect differing viewpoints and experiences.
- **Constructive Feedback** — Provide helpful and actionable feedback.
- **Collaboration** — Work together to improve the project.

Examples of unacceptable behavior include:

- Personal attacks or harassment
- Discriminatory language
- Spamming or promotional misuse of project spaces
- Sharing private information without consent

---

## Maintainer Responsibilities

The AdventureLog maintainers are responsible for enforcing this Code of Conduct and maintaining a respectful community.

If necessary, maintainers may:

- moderate comments
- close pull requests
- remove contributions
- restrict participation

These actions will only be taken when necessary to protect the community and the project.

---

## Scope

This Code of Conduct applies to all spaces related to AdventureLog, including:

- GitHub repositories
- GitHub Discussions
- documentation
- social media
- community spaces

---

## Reporting Issues

If you experience or witness unacceptable behavior, please contact the maintainers at:

```
contact@adventurelog.app
```

All reports will be handled confidentially.

---

## Attribution

This Code of Conduct is inspired by the
Contributor Covenant (v1.4) and adapted for the AdventureLog community.