XF 2.1 XenForo addons and version control

[eberkund]

I am developing an XenForo addon and I would like to store my addon source code using Git.

What is the recommended approach for the generated files?

Version them? do not track them?

 

[Jeremy P]

Add _data/ and _releases/ to your .gitignore, as they are only relevant for building and releasing the add-on for distribution/production. You should track the _output/ directory. You can arguably ignore _metadata.json files too, as they make staging non-trivial commits error prone and tedious, and make merge conflicts painful when collaborating. However, you should be aware that ignoring them does mean certain things (namely adding phrases to the global cache) won't be tracked properly.

 

[Mike]

You can arguably ignore _metadata.json files too

Don't do that. I know they can cause merge conflicts, though they're relatively easy to resolve (you can just pick one) as it would tend to happen with templates an an import afterwards should sort it (along with any necessary version change). But ignoring this would completely break things like version tracking and change detection in templates, as well as some other behaviors with phrases as you noted.

 

[Xon]

_metadata.json files are utterly useless if you are collaborating with someone as you'll must do an php cmd.php xf-dev:import --addon="<addon>" invocation anyway. XF only does hot-reloading on template changes, which is fairly useless for all the other data types. The template change checking doesn't track template modifications, so for add-on development purposes might as well not exist.

At which point, you might as well just wrap that in a script and just do an import for any change. It isn't like the in-XF change history is actually useful if you have everything version controlled anyway.

Yes, not tracking _metadata.json for phrase means the global phrase cache doesn't get used. But most of the time, it makes sense to use phrase groups instead.

 

[Sim]

Note that if you run multiple sites and want to automate the deployment of production-ready code directly from git using tools such as DeployHQ, then you'd also want to track _data - but in a separate branch (don't have both _data and _output together in the same branch!).

I have both a develop branch (tracks _output) and a master/production branch (tracks _data).

It becomes a bit cumbersome to track (there's a workflow you need to strictly follow when checking in code), but it works.

If you're only deploying to one production site - I wouldn't bother, just install the release zip file for production.

We currently run 8 sites and there are a set of custom addons which get deployed to every site. Automating deployment saves a heap of time and ensures we don't accidentally miss a site when pushing out new versions of addons!

 

[DragonByte Tech]

Note that if you run multiple sites and want to automate the deployment of production-ready code directly from git using tools such as DeployHQ, then you'd also want to track _data - but in a separate branch (don't have both _data and _output together in the same branch!).

I'd say that technically, it's fine to have both _data and _output in the same branch, just as long as all collaborators remember to install the addon via CLI rather than the UI.

I generate releases via some webhook trickery, I just have a script set up to delete _output after the files have been copied to the correct folder that the download generation will read from.

 

[Jeremy P]

Don't do that. I know they can cause merge conflicts, though they're relatively easy to resolve (you can just pick one) as it would tend to happen with templates an an import afterwards should sort it (along with any necessary version change). But ignoring this would completely break things like version tracking and change detection in templates, as well as some other behaviors with phrases as you noted.

Template change detection continues to work just fine as the _metadata.json file still exists (or gets created) on developer machines. I could see how version tracking could get mangled, but as far as I'm aware it's mostly relevant for building releases. So long as you build releases from a single machine with a canonical _metadata.json, I think it should continue to work as expected. I take your point that the canonical _metadata.json could be lost (a situation that version control was designed to prevent), but the cognitive overhead of having to stage development output in two different places for each template/phrase/etc and constantly rebase/fixup merge conflicts is a tough sell.

In the long term, it would be nice if version information was stored elsewhere and only updated when releases are built (ie compare to the last time a release was built, and update the version number only if it has changed since). Then it could be tracked without running into these issues.