|
| 1 | +# Contributing to Loop |
| 2 | + |
| 3 | +Thank you for your interest in contributing to Loop. |
| 4 | + |
| 5 | +Loop is a community effort, and contributions of all kinds are welcome. This document outlines some guidelines, good practices, and expectations for contributing to the project, with the goal of making collaboration and review as smooth as possible. |
| 6 | + |
| 7 | +Whether you are helping other users, improving documentation, translating the app, testing builds, reviewing code, or contributing new features and fixes, your work matters. |
| 8 | + |
| 9 | +Loop is built using the LoopWorkspace repository. The primary source for the app is at https://github.com/LoopKit/LoopWorkspace. |
| 10 | + |
| 11 | +## Ways to contribute |
| 12 | + |
| 13 | +There are many ways to support the Loop community: |
| 14 | + |
| 15 | +- **Help others** by answering questions and guiding users in support communities. |
| 16 | +- Improve the **documentation** by updating or expanding LoopDocs. |
| 17 | +- Improve the **app** by contributing code, fixes, features, or tests. |
| 18 | +- Help with **translation and localization** through Loop lokalise. |
| 19 | +- Support **testing and feedback** by validating changes and reporting issues clearly. |
| 20 | + |
| 21 | +### Pay it forward |
| 22 | + |
| 23 | +If Loop has helped you manage your diabetes successfully, consider paying it forward by helping others. Answering questions in [Loop Zulipchat](https://loop.zulipchat.com/) or the [Loop and Learn](https://www.facebook.com/groups/LOOPandLEARN) Facebook group can make a real difference for someone getting started. |
| 24 | + |
| 25 | +### Translate |
| 26 | + |
| 27 | +Loop is translated into multiple languages to make it easier to understand and use around the world. Translation for the submodules that make up the Loop app is managed through the [Loop lokalise project](https://loopkit.github.io/loopdocs/faqs/app-translation/#code-translation) and does not require programming experience. |
| 28 | + |
| 29 | +If your preferred language is missing, or you would like to improve an existing translation, please sign up as a translator following the directions in the link above. |
| 30 | + |
| 31 | +### Develop |
| 32 | + |
| 33 | +Do you work with Swift? UI/UX? Testing? API optimization? Data storage? |
| 34 | + |
| 35 | +Loop is a collaborative project, and contributions of all kinds are welcome. Whether you are writing code, improving the user experience, testing builds, helping with documentation, or contributing in other ways, your help matters. |
| 36 | + |
| 37 | +## General principles |
| 38 | + |
| 39 | +- Start small. Smaller, focused contributions are easier to review, test, and merge. |
| 40 | +- For larger changes or new features, open or reference an issue first so there is a clear place for discussion and progress tracking. |
| 41 | +- Reach out early if you are planning to work on something substantial, especially if it may overlap with work already in progress. |
| 42 | +- Keep discussions constructive, respectful, and focused on improving Loop for the community. |
| 43 | +- Remember that Loop is part of a wider open source AID ecosystem. Collaboration and maintainability matter just as much as shipping features. |
| 44 | + |
| 45 | +## Development guidelines |
| 46 | + |
| 47 | +### Coding conventions |
| 48 | + |
| 49 | +- Use Xcode and follow the existing formatting and style used throughout the codebase. |
| 50 | +- Keep indentation and formatting consistent in every file you change. |
| 51 | +- Format your code before committing. |
| 52 | +- Avoid unrelated formatting-only changes in files you are not otherwise modifying. |
| 53 | +- Choose clear, readable code over clever or overly compact solutions. |
| 54 | +- Follow existing naming, file organization, and architectural patterns unless there is a good reason not to. |
| 55 | + |
| 56 | +### Strings and localization |
| 57 | + |
| 58 | +- Add new user-facing strings in the appropriate localization mechanism used by the app. |
| 59 | +- Provide English source strings only unless the contribution is specifically about translations. |
| 60 | +- Translation and localization for other languages should go through the [Loop lokalise project](https://loopkit.github.io/loopdocs/faqs/app-translation/#code-translation). |
| 61 | + |
| 62 | +### Documentation |
| 63 | + |
| 64 | +- Update docstrings when your change affects setup, configuration, behavior, workflows, or troubleshooting. |
| 65 | +- Keep documentation changes clear and practical. |
| 66 | +- ocumentation contributions are just as valuable as code contributions. |
| 67 | + |
| 68 | +## Branches, commits, and pull requests |
| 69 | + |
| 70 | +### Getting started |
| 71 | + |
| 72 | +The example below is for the Loop repository. Similar contributions can be made to other respositories as needed. |
| 73 | + |
| 74 | +1. Fork the `dev` branch of the [Loop repository](https://github.com/LoopKit/Loop) on GitHub. |
| 75 | +1. Create a separate branch for each feature or fix with an [appropriate name](#branch-names). |
| 76 | +1. Branch from the most recent appropriate development branch (typically `dev`). |
| 77 | +1. Commit your changes to your fork. |
| 78 | +1. When ready, open a pull request against the upstream repository (`LoopKit/Loop`). |
| 79 | + |
| 80 | +### Before opening a pull request |
| 81 | + |
| 82 | +- Rebase or otherwise sync your branch with the latest target branch. |
| 83 | +- Make sure your change is focused and does not include unrelated edits. |
| 84 | +- Test your changes as thoroughly as you reasonably can. |
| 85 | +- Update relevant documentation when needed. |
| 86 | +- Double-check for debug code, commented-out code, accidental version changes, or temporary workarounds left behind. |
| 87 | + |
| 88 | +### Pull request guidance |
| 89 | + |
| 90 | +- Keep pull requests as small and focused as practical. |
| 91 | +- Use a clear title and description. |
| 92 | +- Explain **what** changed and **why**. |
| 93 | +- Link the relevant issue when applicable. |
| 94 | +- Mention any areas that need particular review attention. |
| 95 | +- Be open to feedback and follow-up changes during review. |
| 96 | +- Use AI tools, if at all, as a support for small, well-understood tasks rather than to generate large parts of a contribution |
| 97 | +- Do not submit AI-heavy or "vibe-coded" pull requests; we welcome thoughtful use of tooling, but contributions need to be intentionally designed. |
| 98 | + |
| 99 | +## Naming conventions |
| 100 | + |
| 101 | +### Branch names |
| 102 | + |
| 103 | +Use short, descriptive branch names that make the purpose of the change obvious. For example: |
| 104 | + |
| 105 | +- `fix/watchstate-sync` |
| 106 | +- `feature/onboarding-target-behavior` |
| 107 | +- `refactor/therapy-editor` |
| 108 | + |
| 109 | +### Pull request titles |
| 110 | + |
| 111 | +Use concise, descriptive pull request titles. Good titles usually start with the type of change, for example: |
| 112 | + |
| 113 | +- `Fix watch state sync timing issue` |
| 114 | +- `Add onboarding step for target behavior` |
| 115 | +- `Update build documentation` |
| 116 | + |
| 117 | +## Communication and coordination |
| 118 | + |
| 119 | +For new ideas, larger features, or work that may affect multiple parts of the app, **discuss it with the community first** — reach out to the contributor core on [Loop Zulipchat](https://loop.zulipchat.com/). This helps reduce duplicate work, avoid merge conflicts, and improve the final design. |
| 120 | + |
| 121 | +## Review expectations |
| 122 | + |
| 123 | +Please remember that Loop is maintained by contributors with limited time. Reviews may take time, and some pull requests may require iteration before they are ready to merge. |
| 124 | + |
| 125 | +To help keep reviews efficient: |
| 126 | + |
| 127 | +- Keep the scope narrow. |
| 128 | +- Explain your reasoning clearly. |
| 129 | +- Respond to review comments directly. |
| 130 | +- Avoid force-pushing large unexplained rewrites during active review unless necessary. |
| 131 | +- AI-assisted work is welcome for limited, well-understood tasks, but contributions should remain author-driven and must be code you fully understand, and can explain. |
| 132 | + |
| 133 | +We do not accept pull requests that are largely AI-generated or submitted without careful engineering judgment, testing, and alignment with Loop’s existing patterns. |
| 134 | + |
| 135 | +## Final note |
| 136 | + |
| 137 | +Loop exists because people choose to contribute their time, knowledge, and care to a shared effort. Thank you for helping improve the project and support the broader open source AID community. |
0 commit comments