Add documentation for updating the template

[seanbudd]

We should update the readme to include instructions for merging the latest changes from the template

[seanbudd]

@nvdaes could you add this?

[nvdaes]

@seanbudd I'll try to add this. I'd like feedback from @CyrilleB79 and @abdel792, since one of my big issues with the template, which made me keeping it outdated, was that I didn't know how to update it properly without copying and paste.

[nvdaes]

I plan to suggest the usage of a combination between merge --allow-unrelated-histories, and git reset template/master -- folder file (pathspec) or git reset origin/main -- readme.md, and fixing conflicts mostly in buildVars.py and pyproject.toml, then add these both files and conclude merge.
This is for reference, in case someone things that a better approach is possible. For example, to update the .gitignore to match exactly the file available in the addonTemplate, without fixing conflicts, after performing git merge --allow-unrelated-histories, we can run: git reset template/master -- .gitignore. This is true for most files and folders, and in my experience, generally just buildVars and pyproject need conflict resolution.

[seanbudd]

Sounds good to me

[abdel792]

Hi @seanbudd and @nvdaes,

I think this is a good approach overall, and much better than manually copying files from the template.

One suggestion would be to make the documentation a bit more explanatory, especially for users who are not very familiar with Git.

First, git merge --allow-unrelated-histories is not a command that everyone knows. Although it is the correct solution here, a short explanation of why it is required would help users understand what is happening instead of simply copying the command.

I also think it would be helpful to explain how to deal with the merge result:

• Keep the add-on's own README.md and CHANGELOG.md.
• Remove the docs/ directory, as it only contains documentation for the template itself.
• Expect conflicts in buildVars.py and pyproject.toml, and explain that these files usually need to be merged manually because they contain both template updates and add-on-specific customizations.
• For most of the remaining files, accepting the version from the template is generally the right choice.

In my opinion, the conflict resolution step is probably the part that will confuse beginners the most. Explaining which conflicts are expected and how they should be resolved would make the whole process much easier to follow.

[abdel792]

@nvdaes One small suggestion: would it make sense to use git restore instead of git reset in the examples?

git reset certainly works, but git restore was introduced to make this kind of operation more explicit. I think it may be easier to understand for users who are not very familiar with Git.

For example, instead of:

git reset template/master -- .gitignore

we could use:

git restore --source=template/master .gitignore

Likewise, keeping the add-on's own README.md and CHANGELOG.md could be done with:

git restore --source=origin/main README.md CHANGELOG.md

The resulting behavior is essentially the same, but I find restore a bit more self-explanatory for beginners.

[abdel792]

One additional suggestion regarding the documentation itself.

Since this guide will likely be more than just a few paragraphs, I wonder if it would make more sense to create a dedicated document under docs/ (for example docs/updatingExistingAddons.md) and simply link to it from the README.

This would leave enough room for a step-by-step guide aimed at users who are not very familiar with Git.

The guide could cover something like:

1. Prerequisites

   • Ensure the working tree is clean.
   • Create a backup or work on a dedicated branch.

2. Adding the template remote

   • Add the AddonTemplate repository as a remote (if not already present).
   • Fetch the latest changes.

3. Merging the template

   • Run git merge --allow-unrelated-histories.
   • Briefly explain why this option is required, as it may not be familiar to everyone.

4. Understanding the merge result

   • Explain that merge conflicts are expected.
   • Reassure users that this is normal and does not necessarily indicate a problem.

5. Resolving the merge

   • Keep the add-on's own README.md and CHANGELOG.md.
   • Remove the template's docs/ directory, since it only contains documentation for AddonTemplate itself.
   • Resolve conflicts in buildVars.py and pyproject.toml, explaining what should typically be kept from the add-on and what should be taken from the template.
   • For most of the remaining files, explain that accepting the template version is generally the correct choice.

6. Completing the merge

   • Stage the resolved files.
   • Commit the merge.

7. If something goes wrong

   • Explain how to abort the merge before committing.

To better illustrate what I have in mind, I've attached a draft of such a document. Of course, it's only a proposal and should be considered as a starting point for discussion rather than a finished document.

I think this would make the update process much less intimidating for users who are not experienced with Git, while also documenting the reasoning behind each step instead of only providing a list of commands.

[CyrilleB79]

Actually, IMO, for new add-ons, the best solution would be to initialize the repo with the content of the template and modify it, deleting unneeded files if necessary, rather than copying and modifying files one by one as we suggest today.

Initialization of local repo

Once you have created your repo on GitHub, clone it locally.
Then go in the folder of your local clone of the repo and run the following to create a branch following the master branch of the template:

git remote add nvaccess        https://github.com/nvaccess/AddonTemplate
git fetch nvaccess
git checkout nvaccess/master
git checkout -b tplMaster

First merge

Then you need to perform a first merge from the template.
All the content of your new repo, if any (e.g. readme, licence), will be lost.

Run the following:

git checkout main
git merge tplMaster --allow-unrelated
git checkout . --theirs
git add .
git commit -m "Initialize from Add-on template"
git push

Then you can start developping your add-on, customizing its files (readme.md, buildVars.py, etc ) and adding new ones.

Update to latest template

After a while, you will have put new commits in your main branch.
In parallel, the add-on template may have evolved and its master branch will have moved forward.

Each time you want to update your add-on from the template, do the following:

First, retrieve the latest changes from the add-on template:

git checkout tplMaster
git pull

Then start merging the latest changes of the template to your main branch:

git checkout main
git merge tplMaster

Here, you will likely have a conflict.
Keep your version of the readme.md:

git checkout readme.md --ours

Manually solve other conflicts, e.g. in buildVars.py.
Then finish your merge with the following commands:

git add .
git commit
git push

---

There is also a way to update from template for add-ons which have been created without having been initialized as explained here.
I do not know if it's worth writing it and how.

[CyrilleB79]

Sorry, I had not seen @abdel792's messages and draft.

Let's start from @abdel's draft which is much detailed and clearer. My comment regarding how to initialize the add-on, i.e. do it te other way around than today, still stands though.

Also using git restore is actually a more modern syntax than git checkout --theirs/--ours

[nvdaes]

Thanks @seanbudd @abdel792 and @CyrilleB79 .
Then, unless you raise concerns, I'll create a PR using Abdel's draft, and changing it as appropriate, for your review.
I've though about using:

restore docs *.md --source=origin/main

And also, recommend to fix confilcts in buildVars.py and pyproject.toml in the firs place, and then run the following command:

git add buildVars.py pyproject.toml

Also, I think that it's very important to restore site_scons/** and .vscode/**
I have a lot of conflicts with these.
I plan to create the PR tomorrow or during this weekend, giving time to manifest any concern before.

[nvdaes]

Also, for reference, I'm doing:

git add .
uv sync

And, after updating dependencies with uv, scons to check that no syntax errors are raised due to remaining conflicts.

[abdel792]

Thanks a lot @CyrilleB79 and @nvdaes for your very constructive feedback. I really like the direction this discussion is taking.

I also agree that git restore is a more modern and more intuitive command than git reset, especially for users who are not very familiar with Git.

Using:

git restore --source=origin/main docs *.md

for the add-on-specific documentation also makes sense to me. In practice, add-on repositories usually only contain README.md and CHANGELOG.md at the repository root, and using *.md also covers the case where a developer has added other Markdown files that should be preserved.

The only point I'm still wondering about is the docs/ directory. Since it only exists in AddonTemplate and is not intended to be part of an add-on repository, does restoring it from origin/main reliably remove it from both the index and the working tree after the merge?

If so, I think it would be worth adding a short explanation in the documentation, as it may not be immediately obvious to readers why restoring a path that doesn't exist in origin/main effectively removes it.

[CyrilleB79]

Let's not try to list all the files that users need to keep from add-on, from template or have merge conflict. We can just list examples of one of 2 files for each type without trying to provide commands which would always work.

For example:

• readme.md usually needs to be taken as is from the add-on
• .gitignore or .github are usually taken from the template
• buildVars.py is often merged

But let's not present it as an immuable truth.
For example, in my add-ons:

• Character Information: I have modified sconstruct to build character database
• NVDA Dev & Test Toolbox: I have modified the action build_addon.yml to test the add-on against all versions of NVDA it supports since this add-on is quite sensible to NVDA's API and supports a wide range of version of NVDA.

So in these specific cases, I need to merge these files; but they should not be considered a general rule. Usually, users would not modify them and rather include the changes made in the template for them.

[CyrilleB79]

Thanks also @nvdaes for mentioning uv commands / updates. It's indeed worth documenting this too.