Should I track .cfg files and src/ directory in source control?

Using Plone Customizing Plone
#1

I have a project that is set up which uses 15-20 custom add-on packages. Of which, most of them are add-on packages that I have developed to extend/modify certain features, content types, portlets, dashboards, and Web APIs.

When I have read through project provisioning and deployment documentation, it mentions Ansible playbooks, performance tuning tips, and system maintenance aspects.

See: https://docs.plone.org/manage/deploying/index.html

What I am trying to locate is something that describes the best practices for tracking a Plone site as a git repo. I have found an unofficial .gitignore proposed @ https://github.com/buildout/buildout/blob/master/.gitignore.

So specifically should I just make the Plone/ root directory the git repo's root directory? Should I track the src/ directory? Should I track the buildout.cfg among other *.cfg files?

Also, most of the documentation covers individual add-on src structure, but is there any naming convention for the Plone directory since I might have multiple sites and cannot have multiple /my/git/server/plone.git repos. Any guidance is much appreciated. Thank you in advance!

#2

From the Plone training, this is the closest thing that I can identify that suggests the site itself should be its own single add-on. See: https://training.plone.org/5/mastering-plone/buildout_1.html#a-real-life-example

The buildout.cfg then refers to a repo which has its own buildout.cfg. Maybe this is the only correct way now. https://github.com/collective/ploneconf.site.

#3

Track all *.cfg but not .*.cfg. The src (or whatever is set as sources-dir = ... in buildout) is not needed to be included, since those files are usually in an repository on their own (rare exception: mr.developer sources of kind fs).

#4

Thank you, jensens. So if a Plone developer wants to create a custom site package that contains many internal customizations, then the package mypackage.site would live as its own add on in the sources-dir.

Would that look like option 1 or option 2 below in terms of project structure?

/Plone/
    - buildout.cfg
    - versions.cfg
    + src
        + mypackage.site
    - PloneUnifiedInstaller.tgz

-OR-

/mypackage.site/
    - buildout.cfg
    - versions.cfg
    + src
        + collective.addon
        + etc
   - PloneUnifiedInstaller.tgz
#5

This depends on....

If I have one "policy" package (custom site package) I tend to mix both, buildout and packages. Then all my dependencies are going into a devsrc folder (buildout: sources-dir = ${buildout:directory}/devsrc) - and its in gitignore.
Then under src is my policy package and buildout and policy is in one repository.

Some larger projects of mine have more than one package, i.e. a mycompany.myproject.theme and a mycompany.myproject.site - and maybe a migration package or others project related. In this case I have several repsoitories, one for buildout and for each package. All handled by mr.developer. Then I keep all under src, together with collective add-ons etc.

So both is fine, choose whats simple for your workflow.

#6

We use 2 packages directories in our buildout nowadays. The ‘src’ directory contains packages like the project.policy addon and possibly a theme package, which are part of the main git repo. It doesn’t make sense for these packages to have individual release cycles from the main buildout.

Then we have a separate devel or checkouts directory which is in .gitignore and contains checkouts managed by mr.developer. We put shared packages in here with their git repo, like custom contenttypes (maybe a also the theme package if it is shared between projects. )
These packages are in the always-checkout buildout variable.

If we sometimes need to check out a collective or plone core packages to fix/test with branches, those are also added to the ‘sources’ list.
This minimizes release steps for the project buildout.

#7

I think @fredvd nailed it: If policy/theme are release wise bound directly to buildout, then separate repositories are pointless.

#8

Thank you for your valuable insights,@jensens and @fredvd. Mr.developer seems to be a key player here. I am going to read up. For anyone with a similar interest, see: https://training.plone.org/5/mastering-plone/buildout_1.html#mr-developer, which ultimately refers to: https://github.com/fschulze/mr.developer.

Plone Foundation Code of Conduct