Safe editing in someone else's project

Why this matters

Being allowed to push to a repository is a matter of permissions; being welcome to is a matter of habits. Maintainers merge changes from people who follow the rules below without a second look, and grow cautious with people who do not. The rules are small; together they are what "working safely in a team" means at the file level.

The ten rules

1. Never on main. Create a branch for every change, however small (Section 6). On most projects main is protected and you could not push anyway; the habit matters for the rest.
2. One change per branch. A typo fix and a new page are two branches and two merge requests. Small changes get merged the same day; bundles wait for weeks.
3. Start from an up-to-date main. git switch main && git pull before branching, so your change applies to the current version.
4. Read the conventions first. CONTRIBUTING.md, the merge request template, the .editorconfig, the way existing files are named and organized. Imitate; do not innovate in your first ten changes.
5. Stay in your colour zone. Green files (docs, data, README) freely; amber (source, tests, config) with a developer's eye on the review; red (.git, lock files, generated output) never (lesson 1.2).
6. Edit in the project folder, with the project's editor settings. No copying files out and back; no reformatting a whole file "to clean it up". Your diff should contain only the lines you meant to change.
7. Run what the pipeline runs before you push. For documentation, the Markdown linter; for code, the tests (python3 -m unittest … in the playground). Ten seconds locally saves a red pipeline and a review round.
8. Read your own diff before committing. git diff --staged. Look for debug lines, stray files, whole-file changes (line endings), mode changes.
9. Explain the change. A commit message with the issue number, and a merge request description that says what and why. A reviewer who understands the intent reviews faster and kinder.
10. Ask early when unsure. A question in the issue or a draft merge request costs a minute; a wrong change in main costs a rollback.

Small code changes without being a developer

You will sometimes be asked to change a value, a message, a label or a link inside source code. That is fine, with three additions to the rules:

• Change only the literal text, not the structure around it: the words inside quotes, a number, a URL. If the change needs anything else, hand it to a developer.
• Keep the formatting exactly: the same quotes, indentation and punctuation. In Python, indentation is meaning; in JSON, a missing comma breaks everything.
• Run the program and the tests. If a test fails on the message you changed, the test also needs updating — mention it in the merge request and let the reviewer decide.

print(f"{len(trails)} trail(s)")

Changing trail(s) to trails found is safe. Changing len(trails) is not, unless you know what it does.

Common mistakes

• Reformatting on save. Editors with "format on save" can rewrite a whole file. Turn it off for repositories that do not use a formatter, or check the diff and restore unrelated changes.
• Fixing three unrelated things "while I'm here". Three branches.
• Committing local test data, personal notes or .env. Read the status before git add ..
• Silently changing behaviour with a "docs" change, for example editing a configuration value in a YAML file next to the documentation. Configuration is amber; say so in the merge request.