cookiecutter-amu-thesis/README.md

Template for AMU thesis
=======================

The template itself is in the `{{cookiecutter.thesis_type}}-{{cookiecutter.thesis_surname}}`.

In order to generate a project from the template:

* install cookiecutter
* find a cookiecutter-amu-thesis release applicable (usually the latest release/tag listed at <https://git.wmi.amu.edu.pl/filipg/cookiecutter-amu-thesis>), say VERSION
* run: `cookiecutter https://git.wmi.amu.edu.pl/filipg/cookiecutter-amu-thesis.git --checkout VERSION`
* configure a repository called `msc-YOURSURNAME` at
  <https://git.wmi.amu.edu.pl> (see
  <http://filipg-jenkins.wmi.amu.edu.pl/Repos> for more information), grant read and write
  access rights to Filip Graliński

Interoperation with Overleaf
----------------------------

Overleaf handles git but it's very cr*ppy. It's better to upload a
package to Overleaf first:

0. You need LaTeX installed (e.g. in Ubuntu, you'd need to do: `sudo apt install texlive-latex-full`).
1. Create a project locally.
2. Run `make`
3. Run `make source-pack`
4. Check whether you have an account at http://filipg-jenkins.wmi.amu.edu.pl:8090,
   if not, sign up there (see also http://filipg-jenkins.wmi.amu.edu.pl/Jenkins).
5. Send the zip file to Filip Graliński along with your login at Jenkins and wait for the reply.
6. Copy project to some other place.
7. Clone the repo from Overleaf: `git clone https://git.overleaf.com/FUNNY-OVERLEAF-CODE PAPERID-paper`
8. Set remotes:

```
git remote add overleaf https://git.overleaf.com/FUNNY-OVERLEAF-CODE
git remote set-url origin git@git.wmi.amu.edu.pl:YOURID/YOUR-GITLAB-REPO
```

8. Set credential helper so that stupid Overleaf won't ask about
   password: `git config credential.helper "cache --timeout=10000000"`
9. Unfortunately, Overleaf will discard hidden files (`.*`) when a zip
   is uploaded, also file permissions will be somewhat broken (did I
   tell you how much I hate Overleaf?)
10.  … so you need to copy `.cookiecutter.yml` file and re-apply the template (`cookiecutter https://git.wmi.amu.edu.pl/filipg/cookiecutter-amu-thesis.git --checkout VERSION --output-dir .. --config-file .cookiecutter.yml --no-input --overwrite-if-exists`)
11. Re-commit the files (including recovered `.*` files).
12. Push the repo to Overleaf (fortunately, the `.*` will be treated
    correctly when this is done by git): `git push overleaf master`
13. Push the repo to GitLab. `git push origin master`
14. Set the Overleaf git remote in `helpers/vars`
15. Now you can synchronize between GitLab repo and Overleaf manually or using `helpers/synchro.sh` script

Updating package with updated template
--------------------------------------

To keep your codebase in sync with template you need to occasionally reapply the template.
Here's how:

* find a cookiecutter-amu-thesis release/tag applicable, say VERSION
* (do *not* refer to master in your projects!)
* go to project root
* run: `cookiecutter https://git.wmi.amu.edu.pl/filipg/cookiecutter-amu-thesis.git --checkout VERSION --output-dir .. --config-file .cookiecutter.yml --no-input --overwrite-if-exists`
* check changes with git

### Releasing a new version of the template

* add an item to `CHANGELOG.md`
* in case of breaking changes (_M_ is incremented) describe clearly
  what actions are to be taken in `CHANGELOG.md`
* tag master with the version