Merging Template Changes into Your Extension

Why merge?

As explained on the Your First Extension wiki page, the best-supported and easiest way to create an extension is to use the paranext-extension-template repo.

Merging the paranext-extension-template repo into your extension's repo allows you to receive the latest updates and improvements to paranext-extension-template in your extension.

Additionally, the way in which paranext-core interacts with extensions might change over time. Your extension must stay up-to-date with any breaking changes that occur. Whenever breaking changes are introduced in this relationship, a notification will be sent out on the platform-changes channel on the Platform.Bible Discord server explaining the changes and how to update your code.

If breaking changes are introduced, relevant code will be updated in paranext-extension-template to make sure it stays functional. The easiest first step to updating your own extension's repo to make sure it continues to work with paranext-core is to merge the paranext-extension-template repo into your own extension's repo. Then you may need to make further adjustments to your extension code to make it work with paranext-core.

How to merge

Use the following commands to merge the paranext-extension-template repo into your extension's repo. These commands should be run from the root of your extension's repo.

1. Add the paranext-extension-template as a remote. (Note: This command has to be run only once. If you're merging in more changes from the template at a later time, the remote should still be configured)

git remote add template https://github.com/paranext/paranext-extension-template

2. Fetch changes from the template repo. (Note: This command must be run everytime you're merging in changes from the template repo)

git fetch template

3. Make sure you're on the right branch of your repository before you execute the merge

git checkout <branch-to-merge-to>

4. Perform the merge

In most cases the <branch-to-merge> will be main.

git merge template/<branch-to-merge> --allow-unrelated-histories

5. Finalize

This should resolve any breaking changes. Of course a number of basic operations might still be needed, like:

• Resolving any merge conflicts
• Running npm i from the root of your repo

Note: The merge/squash commits created when updating your repo from the template are important; Git uses them to compare the files for future updates. If you edit your repo's Git history, please preserve these commits (do not squash them, for example) to avoid duplicated merge conflicts in the future.

---

For more information on merging changes from one repo to the other, refer to this StackOverflow page.

For more information on the --allow-unrelated-histories option, refer to this website.