Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (142 loc) · 4.6 KB

CONTRIBUTING.md

File metadata and controls

203 lines (142 loc) · 4.6 KB
Raw

Contributing To MeadowPy

Thanks for helping improve MeadowPy. The project is designed to be friendly to beginners, so contributions should preserve that spirit in both code and user experience.

Useful docs:

Ways To Contribute

Good contribution areas include:

  • Bug reports.
  • Reproduction steps for confusing behavior.
  • Beginner-focused feature ideas.
  • Documentation improvements.
  • Example library additions.
  • Tests for existing behavior.
  • UI polish that makes the app easier to understand.
  • Bug fixes.

Before Changing Code

  1. Read Development Guide.
  2. Read Architecture for the area you are changing.
  3. Set up development dependencies:
dev\setup-dev.bat
  1. Run the full test suite once:
dev\Run Tests.bat

This confirms your environment is working before you start editing.

Development Setup

From the project root:

dev\setup-dev.bat

This calls:

setup.bat --dev

It creates or repairs .venv, installs app dependencies, and installs test dependencies.

Running MeadowPy From Source

From the project root:

.venv\Scripts\python.exe -m meadowpy

Running Tests

Run the full suite:

dev\Run Tests.bat

Run a targeted test without coverage:

.venv\Scripts\python.exe -m pytest -c dev\pytest.ini --no-cov dev\tests\test_settings.py -q

See Testing for the full testing workflow.

Pull Request Expectations

A good pull request should:

  • Explain what changed and why.
  • Keep the scope focused.
  • Include tests for behavior changes.
  • Update docs for setup, workflow, shortcut, AI, architecture, or testing changes.
  • Avoid unrelated formatting churn.
  • Avoid changing generated coverage output.
  • Preserve beginner-friendly wording in user-facing text.

Before submitting:

  1. Run relevant targeted tests.
  2. Run the full test suite.
  3. Launch the app if UI behavior changed.
  4. Check changed files for accidental edits.

Bug Reports

Useful bug reports include:

  • What you were trying to do.
  • What happened.
  • What you expected.
  • Steps to reproduce.
  • MeadowPy version, if known.
  • Windows version.
  • Python version.
  • Whether Ollama was involved.
  • Any relevant log details from:
%USERPROFILE%\.meadowpy\meadowpy.log

Avoid posting private code, secrets, API keys, or personal files in public bug reports.

If this repository is hosted on GitHub, use the bug report issue template so the environment and reproduction details are captured consistently.

Feature Requests

Helpful feature requests explain:

  • The beginner problem being solved.
  • The workflow where the feature would appear.
  • What a user should be able to do after the feature exists.
  • Any examples from other tools, if relevant.

MeadowPy should stay approachable. Features that add power should also protect clarity.

If this repository is hosted on GitHub, use the feature request issue template for feature ideas.

Documentation Contributions

Documentation changes are welcome.

When editing docs:

  • Keep commands exact.
  • Keep paths exact.
  • Prefer short sections with clear headings.
  • Link to related docs instead of repeating large sections.
  • Keep beginner-facing instructions concrete.
  • Update Shortcuts when shortcuts change.
  • Update Architecture when ownership or flow changes.

If this repository is hosted on GitHub, use the documentation issue template for stale, missing, confusing, or incorrect docs.

Example Library Contributions

Examples should be:

  • Beginner-friendly.
  • Safe to run.
  • Well-commented.
  • Focused on one concept or small project.
  • Free of secrets, network requirements, and destructive file operations.

Add examples under:

meadowpy\resources\examples

Then add the example to:

meadowpy\resources\examples\catalog.json

Coding Guidelines

General guidelines:

  • Follow existing patterns before adding new abstractions.
  • Keep UI work on the UI thread.
  • Use Qt signals for worker-to-UI communication.
  • Keep long-running work in background workers or subprocesses.
  • Keep user-facing messages clear and beginner-friendly.
  • Prefer small, testable changes.
  • Update tests near the behavior you changed.

Security Issues

Do not report security-sensitive issues publicly if they include exploit details, private data, or a way to harm users.

Use the guidance in Security.