Documentation about using the template from Git

[nvdaes]

Description

Documentation about integration of the add-on template in add-ons using git.

Related issues

Fixes #37

Credits

This work comes from ideas provided by @abdel792, @CyrilleB79, and other contributors.

[abdel792]

Thanks @nvdaes, this is a really solid improvement and the guide is now much clearer and more structured. The separation between setup, update, and troubleshooting makes it much easier to follow.

I think we are very close to a consistent and usable workflow for non-Git experts, but there are a few key clarifications that would make the system fully deterministic and easier to reason about.

---

1. Global rule (important for consistency)

I think we should explicitly define a single global priority rule for all files:

Except for three explicitly defined categories, all files should be updated from AddonTemplate with priority during the merge process.

The three exceptions are:

• Project-owned files (always preserved from the add-on):

  • README.md
  • CHANGELOG.md

• Hybrid files (manual merge required):

  • buildVars.py
  • pyproject.toml

• Template-only files (must be removed):

  • docs/

---

Everything else (including .github/, .gitignore, workflows, etc.) should be considered as coming from AddonTemplate and used as the default version during updates.

This rule would make conflict resolution much more predictable and avoid case-by-case decisions.

---

2. docs/ handling should be made more explicit

The current instructions are correct, but it might help to clearly state the intent:

The docs/ directory belongs exclusively to AddonTemplate and must not remain in the final add-on repository.

Because of that, it should always be removed during the update process.

For clarity, it might be better to present a single recommended approach:

git rm -r docs

rather than presenting multiple equivalent alternatives, to reduce ambiguity for beginners.

---

3. Clarification on git restore

The use of git restore is a very good improvement compared to older Git patterns.

However, it might be worth clarifying its intent in this context:

• it is used to restore files from a known source state
• in this workflow, it helps enforce the rule “keep add-on files for project-owned content”

One subtle point: when restoring from HEAD, it is effectively reinforcing the current add-on state, not pulling from the template, which may not be immediately obvious to beginners.

Adding a short explanation could help avoid confusion.

---

Overall suggestion

I think the document is now very close to a solid “official workflow”, and these clarifications would mainly help:

• reduce ambiguity during conflict resolution
• make file ownership rules explicit
• avoid beginners having to infer intent from Git commands

Overall though, this is a big step forward compared to the previous copy/paste approach 👍