From 2c58320fa00b042eac049ef59b8c6dda98e0bd8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Noelia=20Ruiz=20Mart=C3=ADnez?= Date: Fri, 3 Jul 2026 22:47:48 +0200 Subject: [PATCH 1/4] Documentation about using the template from Git --- .../updatingExistingAddons.md | 171 ++++++++++++++++++ readme.md | 23 +++ 2 files changed, 194 insertions(+) create mode 100644 docs/managementFromGit/updatingExistingAddons.md diff --git a/docs/managementFromGit/updatingExistingAddons.md b/docs/managementFromGit/updatingExistingAddons.md new file mode 100644 index 0000000..f6fcd4e --- /dev/null +++ b/docs/managementFromGit/updatingExistingAddons.md @@ -0,0 +1,171 @@ +# Updating an Existing Add-on + +As AddonTemplate evolves, it receives improvements, bug fixes, new GitHub workflows, and build system updates. + +If your add-on was created from an older version of AddonTemplate, you can merge the latest template changes into your repository instead of manually copying updated files. + +This document explains the recommended update procedure. + +> [!NOTE] +> Updating from AddonTemplate only affects your project's infrastructure (build scripts, GitHub workflows, configuration files, etc.). It does **not** modify your add-on's source code. + +## Before you begin + +Before updating your repository: + +- Ensure your working tree is clean. + + ``` + git status + ``` + +- Commit or stash any pending changes. + +- It is recommended to perform the update on a dedicated branch. + +If anything goes wrong before the merge commit is created, you can safely cancel the operation using: + +``` +git merge --abort +``` + +## Adding the template repository + +If you have not already done so, add AddonTemplate as a remote: + +``` +git remote add template https://github.com/nvaccess/AddonTemplate.git +``` + +Then fetch the latest changes: + +``` +git fetch template +``` + +## Merging the latest template + +Merge the latest version of AddonTemplate: + +``` +git merge template/master --allow-unrelated-histories +``` + +The `--allow-unrelated-histories` option is required because your add-on repository and AddonTemplate do not share a common Git history. + +At this stage, Git may report merge conflicts. + +This is completely normal. + +## Understanding merge conflicts + +During the merge, Git attempts to combine the contents of both repositories automatically. + +When Git cannot determine which version should be kept, it reports a merge conflict. + +A conflict does **not** mean that something went wrong. +It simply means that some files require manual review. + +## Resolving the merge + +### Keep your add-on documentation + +Your add-on documentation should not be replaced by the template. + +Restore the following files from your current branch: + +``` +git restore --source=HEAD README.md CHANGELOG.md +``` + +### Remove the template documentation + +The `docs/` directory belongs to AddonTemplate itself. + +It is not intended to become part of your add-on repository. + +Remove it: + +``` +git rm -r docs +``` + +### Resolve buildVars.py + +`buildVars.py` usually contains merge conflicts because it includes both: + +- information specific to your add-on; +- variables introduced by newer versions of AddonTemplate. + +Review the file carefully. + +In general: + +- keep your add-on metadata; +- preserve your version number; +- keep your custom settings; +- add any new variables introduced by the template. + +### Resolve pyproject.toml + +`pyproject.toml` is another file that commonly requires manual review. + +Keep your project-specific configuration while incorporating any new settings required by the updated template. + +### Other files + +For most remaining files, the version provided by AddonTemplate is generally the correct one. + +Typical examples include: + +- `.github/` +- `.gitignore` +- `manifest.ini.tpl` +- `manifest-translated.ini.tpl` +- `site_scons/` +- `sconstruct` + +Review any conflicts if necessary before completing the merge. + +## Completing the merge + +Once all conflicts have been resolved, stage the modified files: + +``` +git add . +``` + +Then create the merge commit: + +``` +git commit +``` + +## Summary + +| File or directory | Recommended action | +|-------------------|--------------------| +| `README.md` | Keep the add-on version | +| `CHANGELOG.md` | Keep the add-on version | +| `docs/` | Remove | +| `buildVars.py` | Merge manually | +| `pyproject.toml` | Merge manually | +| Other template files | Usually accept the template version | + +## Troubleshooting + +### I don't understand a merge conflict + +Merge conflicts are expected when updating from a newer version of AddonTemplate. + +Most conflicts occur in `buildVars.py` and `pyproject.toml`. + +Review the conflicting sections carefully and combine the changes from both versions. + +### I want to cancel the update + +If you have not yet committed the merge, you can restore your repository to its previous state: + +``` +git merge --abort +``` \ No newline at end of file diff --git a/readme.md b/readme.md index 3d80f87..4debb07 100644 --- a/readme.md +++ b/readme.md @@ -102,6 +102,29 @@ uv.lock 7. If you create releases with the GitHub workflow, pushing a tag, update the `changelog.md` file with the release description you want to be displayed in on your GitHub release page. 8. In the `[project]` section of `pyproject.toml`, update your project information. +Alternatively: + +1. Create a repository on GitHub, where your add-on will be hosted. Provide readme.md and license files. +2. Add the add-on template as a remote in your repository: + +```sh +cd {repositoryFolder} +git remote add template https://github.com/nvaccess/addonTemplate +``` + +3. Fetch the addonTemplate repository: + +```sh +fetch template +``` + +4. Merge the template, passing the --unrelated-histories flag, since your add-on repository and the repository of the template won't share a common history. Also, pass the --squash flag to avoid having a bunch of commits in the history of your repository: + +```sh +merge template --allow-unrelated-histories --squash + +For more details about updating your add-on repository with files updated in the add-on template, see [updating your add-on from the addon template](docs/managementFromGit/updatingExistingAddons.md). + #### Add-on manifest specification An add-on manifest generated manually or via `buildVars.py` must include the following information: From 6aef8170a2aab1adf685a39bc528ebe5e8464f04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Noelia=20Ruiz=20Mart=C3=ADnez?= Date: Sat, 4 Jul 2026 05:15:24 +0200 Subject: [PATCH 2/4] Update documentation --- .../updatingExistingAddons.md | 98 ++++++++++++++++--- readme.md | 24 +---- 2 files changed, 85 insertions(+), 37 deletions(-) diff --git a/docs/managementFromGit/updatingExistingAddons.md b/docs/managementFromGit/updatingExistingAddons.md index f6fcd4e..c1edc81 100644 --- a/docs/managementFromGit/updatingExistingAddons.md +++ b/docs/managementFromGit/updatingExistingAddons.md @@ -1,8 +1,46 @@ -# Updating an Existing Add-on +# Integrating the add-on template in your add-on + +## Pre-requisites + +1. Create a repository, for example on GitHub, providing readme and license files. +1. Clone the repository: + + ```sh + git clone https://github.com/{repoName}.git + ``` + +1. In the folder where your add-on repository is cloned, create an `addon` submolder and store the code for your add-on. + +1. Go to the folder where your repository was cloned: + + ```sh + cd {repoFolder} + ``` + +1. Commit your changes: + + ```sh + git add . + git commit -m "Initial commit" + ``` + +1. Add the template as a remote: + + ```sh + git remote add template https://github.com/nvaccess/addonTemplate.git + ``` + +1. Fetch the add-on template: + + ```sh + git fetch template + ``` + +## Updating an Existing Add-on As AddonTemplate evolves, it receives improvements, bug fixes, new GitHub workflows, and build system updates. -If your add-on was created from an older version of AddonTemplate, you can merge the latest template changes into your repository instead of manually copying updated files. +You can merge the latest template changes into your repository instead of manually copying updated files. This document explains the recommended update procedure. @@ -15,7 +53,7 @@ Before updating your repository: - Ensure your working tree is clean. - ``` + ```sh git status ``` @@ -23,9 +61,9 @@ Before updating your repository: - It is recommended to perform the update on a dedicated branch. -If anything goes wrong before the merge commit is created, you can safely cancel the operation using: +If anything goes wrong before the merge commit is created, if you haven't passed the `--squash- flag, you can safely cancel the operation using: -``` +```sh git merge --abort ``` @@ -33,13 +71,13 @@ git merge --abort If you have not already done so, add AddonTemplate as a remote: -``` +```sh git remote add template https://github.com/nvaccess/AddonTemplate.git ``` Then fetch the latest changes: -``` +```sh git fetch template ``` @@ -47,12 +85,14 @@ git fetch template Merge the latest version of AddonTemplate: -``` -git merge template/master --allow-unrelated-histories +```sh +git merge template/master --allow-unrelated-histories --squash ``` The `--allow-unrelated-histories` option is required because your add-on repository and AddonTemplate do not share a common Git history. +The ---squash` flags will add changes from the template as a unique commit, instead of several ones, what may be useful to keep a cleaner history on your repository. + At this stage, Git may report merge conflicts. This is completely normal. @@ -68,14 +108,19 @@ It simply means that some files require manual review. ## Resolving the merge +### Using the restore command + +The `restore` command can be used to update files on your working directory, i.e., the folder where your add-on repository was cloned. +The `--source` flag is used to determine where files to be restored can be found. + ### Keep your add-on documentation Your add-on documentation should not be replaced by the template. -Restore the following files from your current branch: +To keep your `.md` files from your add-on repository, ensuring they aren't replaced with files from the template, you can use the following command: -``` -git restore --source=HEAD README.md CHANGELOG.md +```sh +git restore *.md --source=HEAD ``` ### Remove the template documentation @@ -90,6 +135,12 @@ Remove it: git rm -r docs ``` +Or use the restore command: + +```sh +git restore docs --source=HEAD +``` + ### Resolve buildVars.py `buildVars.py` usually contains merge conflicts because it includes both: @@ -164,8 +215,25 @@ Review the conflicting sections carefully and combine the changes from both vers ### I want to cancel the update -If you have not yet committed the merge, you can restore your repository to its previous state: +If you have not yet committed the merge, and you haven't passed the --squash flag to `git merge`, you can restore your repository to its previous state: -``` +```sh git merge --abort -``` \ No newline at end of file +``` + +If you passed the `--squash` flag, `git merge --abort` won't work. In this case, you can use the restore command: + +```sh +git restore . --staged # Discard changes added to the staging area (after using `git add .`) +``` + +```sh +git restore . --source=HEAD # Restores the working directory to the last commit made in your add-on repository +``` + +If you committed changes, you can use: + +```sh +git reset --hard {cleanBranch} +``` + diff --git a/readme.md b/readme.md index 4debb07..9cc497b 100644 --- a/readme.md +++ b/readme.md @@ -102,28 +102,8 @@ uv.lock 7. If you create releases with the GitHub workflow, pushing a tag, update the `changelog.md` file with the release description you want to be displayed in on your GitHub release page. 8. In the `[project]` section of `pyproject.toml`, update your project information. -Alternatively: - -1. Create a repository on GitHub, where your add-on will be hosted. Provide readme.md and license files. -2. Add the add-on template as a remote in your repository: - -```sh -cd {repositoryFolder} -git remote add template https://github.com/nvaccess/addonTemplate -``` - -3. Fetch the addonTemplate repository: - -```sh -fetch template -``` - -4. Merge the template, passing the --unrelated-histories flag, since your add-on repository and the repository of the template won't share a common history. Also, pass the --squash flag to avoid having a bunch of commits in the history of your repository: - -```sh -merge template --allow-unrelated-histories --squash - -For more details about updating your add-on repository with files updated in the add-on template, see [updating your add-on from the addon template](docs/managementFromGit/updatingExistingAddons.md). +Alternatively, you can integrate this template in your add-on using Git. +For more details, read [integrating the add-on template using Git](docs/managementFromGit/updatingExistingAddons.md). #### Add-on manifest specification From 5b2a058adc8c6271701ec94bbd6682b2678742c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Noelia=20Ruiz=20Mart=C3=ADnez?= Date: Sat, 4 Jul 2026 05:25:39 +0200 Subject: [PATCH 3/4] Add note about uv sync --- docs/managementFromGit/updatingExistingAddons.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/managementFromGit/updatingExistingAddons.md b/docs/managementFromGit/updatingExistingAddons.md index c1edc81..194ba15 100644 --- a/docs/managementFromGit/updatingExistingAddons.md +++ b/docs/managementFromGit/updatingExistingAddons.md @@ -180,15 +180,23 @@ Review any conflicts if necessary before completing the merge. ## Completing the merge -Once all conflicts have been resolved, stage the modified files: +Once all conflicts have been resolved, check if the add-on can be built properly: +```sh +uv sync # Update dependencies +uv run scons # Build the add-on ``` + + +If all is right, stage the modified files: + +```sh git add . ``` Then create the merge commit: -``` +```sh git commit ``` From c652e69bb3eae92b55396f008f3ecd7216c87298 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Noelia=20Ruiz=20Mart=C3=ADnez?= Date: Sat, 4 Jul 2026 05:28:36 +0200 Subject: [PATCH 4/4] Fix with pre-commit --- docs/managementFromGit/updatingExistingAddons.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/managementFromGit/updatingExistingAddons.md b/docs/managementFromGit/updatingExistingAddons.md index 194ba15..6ee9650 100644 --- a/docs/managementFromGit/updatingExistingAddons.md +++ b/docs/managementFromGit/updatingExistingAddons.md @@ -244,4 +244,3 @@ If you committed changes, you can use: ```sh git reset --hard {cleanBranch} ``` -