Merge pull request #16 from mononen/contributing-with-submodules

Author: joshuapare

CONTRIBUTING.md

@@ -37,6 +37,89 @@ Unsure where to start? Look for issues tagged with `good first issue`—these ar
 - **Testing**: Adding tests for new features or fixing bugs increases the stability of Omniview. We love tests!
 - **Documentation**: If your changes need documentation, please update it. Good documentation is key to user adoption.
 
+## Working with Forks and Submodules
+
+Omniview uses Git submodules for first-party plugins (e.g. `plugins/kubernetes`). If you're developing across a fork of the parent repo **and** a fork of a plugin, follow this workflow carefully to avoid polluting PRs with submodule URL changes.
+
+### Repository layout
+
+| Repo | Canonical location |
+|------|--------------------|
+| Parent app | `github.com/omniviewdev/omniview` |
+| Kubernetes plugin | `github.com/omniviewdev/omniview-plugin-kubernetes` |
+
+### Setting up your forks locally
+
+After cloning your fork of the parent repo, the submodule will point to the canonical upstream URL (as defined in `.gitmodules`). Add your plugin fork as a second remote inside the submodule so you can push feature branches there:
+
+```bash
+cd plugins/kubernetes
+git remote add upstream git@github.com:omniviewdev/omniview-plugin-kubernetes.git
+# "origin" already points to the canonical upstream after a normal clone
+# add your fork as a push target:
+git remote set-url --push origin git@github.com:<your-username>/omniview-plugin-kubernetes.git
+```
+
+To redirect your local checkout to pull from your fork without touching `.gitmodules` (which is committed and shared):
+
+```bash
+# Run from the root of the parent repo
+git config submodule.plugins/kubernetes.url git@github.com:<your-username>/omniview-plugin-kubernetes.git
+```
+
+This writes only to your local `.git/config` and is never committed.
+
+### Developing a plugin change
+
+1. Branch off your plugin fork, do your work, push to your fork, open a PR to `omniviewdev/omniview-plugin-kubernetes`.
+2. While waiting for the plugin PR to merge you can point your local submodule at your feature branch commit for integration testing — but **never commit a `.gitmodules` change** that points to a personal fork.
+3. Once the plugin PR is merged, advance the submodule pointer in the parent repo:
+
+```bash
+cd plugins/kubernetes
+git fetch upstream
+git checkout upstream/main
+
+cd ..
+git add plugins/kubernetes
+git commit -m "chore: update kubernetes submodule to upstream main (<short-sha>)"
+```
+
+4. Open a PR to `omniviewdev/omniview` with just the submodule pointer bump.
+
+### Syncing your fork after upstream merges
+
+After any PR is merged into the upstream parent repo, sync your fork's `main`:
+
+```bash
+git fetch upstream
+git merge upstream/main
+git push origin main
+```
+
+Then check the submodule too — if `git submodule status` shows a `-` or `+` prefix the pointer is out of sync:
+
+```bash
+cd plugins/kubernetes
+git fetch upstream
+git checkout upstream/main
+
+cd ..
+git add plugins/kubernetes
+git commit -m "chore: update kubernetes submodule to upstream main (<short-sha>)"
+git push origin main
+```
+
+### The rule that prevents collisions
+
+> **`.gitmodules` must always reference the canonical upstream URL.** Never open a PR that changes a submodule URL to a personal fork. Use `git config submodule.<path>.url` for local overrides — these live in `.git/config` and are never committed.
+
+To reset a local override back to the canonical URL at any time:
+
+```bash
+git submodule sync
+```
+
 ## Signing the CLA
 
 Before we can accept your contributions, you'll need to sign a Contributor License Agreement (CLA). This helps ensure that the community can always use your contributions.