Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (83 loc) · 4.47 KB

CONTRIBUTING.md

File metadata and controls

123 lines (83 loc) · 4.47 KB
Raw

Contributing to Ashfolio

We welcome contributions to Ashfolio! Whether you're fixing a bug, adding a new feature, or improving documentation, your help is greatly appreciated. This guide will help you get started and ensure your contributions align with the project's standards.

Code of Conduct

We expect all contributors to be respectful and professional. Please follow standard open source community guidelines:

  • Be respectful of different viewpoints and experiences
  • Give and accept constructive feedback gracefully
  • Focus on what is best for the project and the community
  • Show empathy towards other community members

Unacceptable behavior includes harassment, trolling, insulting comments, or any conduct that would be considered inappropriate in a professional setting.

Getting Started

Before you start contributing, please ensure your development environment is set up correctly. Follow the instructions in Installation Guide.

Once set up, you can get the application running with:

just dev

How to Contribute

1. Find a Task

Check the GitHub Issues for tasks and planned features. If you have an idea for a new feature not listed, please open an issue first to discuss it.

2. Branching Strategy

We use a simple feature branching strategy:

  • Create a new branch from main for each feature or bug fix: 
    git checkout main
git pull origin main
git checkout -b feature/your-feature-name
# or
git checkout -b bugfix/issue-description

3. Implement Your Changes

  • Write clean, maintainable code that adheres to the Ashfolio Coding Standards.
  • Write tests for all new functionality and ensure existing tests pass.
  • Make incremental commits with clear messages.

4. Commit Messages

Write clear, concise, and descriptive commit messages. A good commit message explains what was changed and why.

Example:

feat: Implement transaction CRUD operations

Adds full create, read, update, and delete functionality for transactions.
This completes Phase 9 and allows users to manage their investment records.

5. Pull Request Process

  1. Push your branch to your fork: 
    git push origin feature/your-feature-name
  2. Open a Pull Request on the main Ashfolio repository.
  3. Provide a clear description of your changes, linking to any relevant issues or tasks.
  4. Ensure all checks pass (tests, linting, formatting).
  5. Address any feedback from reviewers.

Coding Standards

Ashfolio adheres to specific coding standards to maintain consistency and quality. Key highlights include:

  • All business logic must be implemented as Ash resources. No direct Ecto usage.
  • Always use Decimal types for monetary values and keep everything in USD.
  • Use Ashfolio.ErrorHandler and ErrorHelpers for consistent, user-friendly error messages.
  • Prefer explicit over clever code. Avoid premature optimizations.

Testing

Maintaining a robust test suite is crucial for Ashfolio's stability. We expect all contributions to include appropriate tests and ensure the entire test suite passes.

  • Always run the full test suite before submitting a pull request:

    just test

  • During development, use targeted commands:

    just test-file <path/to/your_test_file.exs>
just test-watch

  • Aim for high test coverage for new features.

  • Never make real API calls in tests. Use Mox for mocking external services like Yahoo Finance.

  • Be aware of the specific patterns for testing singleton GenServers and shared state, as detailed in our testing documentation.

Documentation

Keep documentation up-to-date. If your changes affect any of the following, please update them:

  • CHANGELOG.md: Summarize your changes for the next release.
  • GitHub Issues: Update any related issues with your progress.
  • docs/development/architecture.md: If your changes impact the overall system design.

Before Submitting a Pull Request - Checklist

  • Your code adheres to the Ashfolio Coding Standards.
  • All new features have corresponding tests.
  • All tests pass (just test).
  • Your code is formatted (just format).
  • Your commit messages are clear and descriptive.
  • You have updated relevant documentation (CHANGELOG, architecture docs if needed).
  • You have pulled the latest changes from main and resolved any conflicts.

Thank you for contributing to Ashfolio!