How to keep your Trellis updated

update-trellis.md

> How did you setup your projects?

More less the same as the subtrees method, but:

• trellis and bedrock are 2 different git repos
• keep .git despite the doc tells you to delete it
• i also have a branch (tangrufus/trellis@project-template) to keep all my common customization to start a project
• 3 git remotes for every project:
  • roots/trellis
  • tangrufus/trellis
  • actual origin of the project

$ git clone -o roots https://github.com/roots/trellis.git www-example-com-trellis
$ cd www-example-com-trellis
$ git remote add tangrufus https://github.com/tangrufus/trellis.git
$ hub create -p
$ git remote -v
origin	https://github.com/TangRufus/www-example-com-trellis.git (fetch)
origin	https://github.com/TangRufus/www-example-com-trellis.git (push)
roots	https://github.com/roots/trellis.git (fetch)
roots	https://github.com/roots/trellis.git (push)
tangrufus	https://github.com/tangrufus/trellis.git (fetch)
tangrufus	https://github.com/tangrufus/trellis.git (push)

## Merge my project temaplate
$ git fetch --all
$ git merge tangrufus/project-template

## Do your job...
## Commit and push to `origin` as usual

## When roots/trellis has been updated...
## Important: Reading change logs, commit messages and `git diff` are necessary
## Tips: Make use of git branches
$ git fetch --all
$ git merge roots/master

Do I recommend everyone to use this method?

No. Use it only if you are comfortable with git. Otherwise, git gives you more headache than benefits.

Should you always keep your forks update with roots/trellis?

Yes! Always! This is actually missing from the doc: the doc tells you to delete .git but gives no instructions about updating.

However, updating Trellis is challenging, I don't think of a good and easy way that suitable for everyone.

Edit: By forks, I mean both origin and tangrufus remotes in the above example.

Avoiding merge conflicts

Since I use git a bit differently than the subtrees method, I got less merge conflicts.

Tips:

• Whenever possible, don't change existing files in roles/*
• When changing j2 templates, make use of variables
• When changing variable values, define them in group_vars/<env>/xxx.yml
• When a j2 template doesn't allow customizing with variables, submit pull requests, example: #856
• When you need to add more tasks:
  • Bad: change existing files in roles/*
  • Good: make a new role and add it into dev.yml / server.yml
  • Best: extract it to galaxy.ansible.com
  • see also: #830, #882
• Whenever possible, don't use Nginx child templates because you lose all the benefits Trellis update gives you

Let say you want to change something in sites-available/example.com.conf:

• Best: define variables in group_vars/<env>/xxx.yml

• Good: template out to {{ nginx_path }}/includes.d/{{ item.key }}/xxx.conf but beware Trellis might delete your files during this task, see how I do it

• Bad: use Nginx child templates is the last resort

• Reading change logs, commit messages and git diff are necessary

• No merge conflict doesn't mean it won't break

• Same commit doesn't mean same server, see: #881 (comment)

The ultimate way to avoid merge conflict

Get it merged into roots/trellis