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.