Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (101 loc) · 5.98 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 5.98 KB
Raw

Thank you for your interest in contributing to MeshCore One!

To make the contribution process smooth and respectful of everyone's time, please follow these guidelines:

Before Starting Work

Discuss your idea first: IF YOU DO NOT FOLLOW THIS STEP, YOUR PR MAY BE CLOSED WITHOUT COMMENT.
Any of the following options are available:

  • File a GitHub issue with your idea
  • MeshCore Discord: Look for the MeshCore One forum post.
  • Or message me on Matrix @avion:matrix.org

Pull Request Requirements

If your PR looks like it hasn't gone through sufficient planning, testing, and review, it will be closed.

When submitting a PR, please:

  • Include a clear description of the feature or fix.
  • Include an overview of the changes made.
  • Keep the PR to a single logical change. Don't bundle unrelated commits, drive-by refactors, or stray edits; open a separate PR for those so each can be reviewed on its own.
  • Run swiftlint lint and fix any warnings or errors.
  • Run the test suite and confirm all tests pass.
  • Describe the testing steps you performed.

If you (or your AI agent) open the PR from the command line or an API (gh pr create, the GitHub REST API, or any bot), the required checklist will be missing and an automated check will close the PR until it is added. Paste the block below into your PR description and complete every item:

## Description

<!-- What does this PR do, and why are you making the change? -->

## Overview of Changes

<!-- A short summary of the changes made. -->

## Testing

<!-- Describe the testing steps you performed, including any edge cases. -->

## Tested on
- [ ] iOS [version]
- [ ] iPadOS [version]
- [ ] macOS [version]

## Checklist

- [ ] This PR was discussed with the maintainer either via GitHub issue or other means (Also check the box if this PR is small enough not to need discussion e.g. typo fix)
- [ ] I have read `CONTRIBUTING.md`
- [ ] Testing steps are documented above.
- [ ] This change is not low effort and I took the time to test it

Important Note for AI-Assisted Contributions

If you're an experienced software engineer and did not rely heavily on AI for your contribution, skip to Getting Started.

If you used AI extensively (which is totally fine, I built this entire project with AI despite not being a SWE and only having basic Python scripting experience), please follow these best practices to ensure high-quality results:

  1. If you have no previous coding experience It's usually easier to simply create a feature request GitHub issue with your idea and then I can implement it using my established workflows. Feel free to create mock ups with AI and attach those screenshots in your feature request!

  2. Choose the right model for planning
    If you're not a software engineer and aren't comfortable creating detailed technical plans yourself, stick to the strongest reasoning models: Claude Opus or GPT Codex (high/xhigh). These are decent at turning non-technical ideas into solid implementation plans. Other popular models (e.g., GLM, MiniMax) perform well when given a detailed plan, but struggle to create one from scratch in a large codebase.

  3. Plan thoroughly
    Ask the AI to use research agents/tools to gather context about the relevant parts of the codebase. Think of edge cases. Write the plan to an md file.

  4. Review the plan
    Start a fresh chat and ask the AI to critically review the plan.

  5. Refine the plan
    Have the AI validate the review, then adjust the plan as necessary.

  6. Implement
    Have the AI follow the finalized plan to make the changes.

  7. Validate the implementation
    In a new chat, ask the AI to review the code changes. Claude Code and Codex both have a built-in review tool for this.

  8. Test thoroughly
    Manually verify that everything works as expected. Test edge cases.

  9. Submit the PR
    In the description, include the reason you are making the changes. You can ask the AI to draft the PR description. Feel free to use it directly, but adding a bit of your own voice is always appreciated!

Getting Started

Prerequisites

  • Xcode 26.0+
  • Swift 6.2+
  • XcodeGen: Required for project file generation.
  • SwiftGen: Required for localization. 
    brew install xcodegen swiftgen
  • xcsift (optional): Transforms verbose Xcode output into concise JSON. 
    brew install xcsift

Project Setup

  1. Clone the repository.
  2. Generate the Xcode project: 
    xcodegen generate
    The project is generated by XcodeGen from project.yml; never edit MC1.xcodeproj directly, as it is overwritten on the next generate. Make project configuration changes in project.yml.
  3. Open MC1.xcodeproj.

Run make help for the full list of developer shortcuts.

Testing

Two simulators are required, because the suites target different iOS versions:

  • App suite runs on iPhone 17e, iOS 26.5: 
    make test-app
  • StoreKit / IAP suites run on iPhone 16e, iOS 18.x: 
    make test-store
    These must run on iOS 18.x: under xcodebuild test the iOS 26.x simulators serve 0 products to StoreKit (an Apple-side SKTestSession regression), so the product-dependent tests would falsely fail. They auto-skip on iOS 26, so make test-store is how you actually exercise them.

make test runs both passes. Override SIM or STORE_SIM if your machine has different simulators installed.

Branch Workflow

  • All development happens on the dev branch. main is reserved for releases.
  • Fork the repo and create your branch from dev.
  • Use the naming convention {type}/short-descriptive-name, where type is one of:
    • feature — new functionality
    • fix — bug fix
    • refactor — code restructuring without behavior change
    • chore — tooling, CI, docs, or other non-code changes
  • Target your PR to dev, not main.

Thank You!

Thank you again for your interest in contributing. I'm excited to see what you build!