Overleaf Workflow

This guide outlines a streamlined process for synchronizing the GitHub development(issue) branch with Overleaf, allowing you to collaborate on .tex documents. When there is an issue that requires to make edits on Overleaf, the approach is as follows:

Workflow

1. Set up Dropbox sync to Overleaf.
2. User imports the relevant /paper_slides/ directory to related Overleaf project via dropbox, and rename it as /paper_slides_issueXX/. If the project does not exist, then please first create a new project (New Project -> Upload Project) and share to collaborators, then import.
3. For text edits, users are recommended to collaborate editing on Overleaf. We do not suggest users to do local .tex edits without sync that to Overleaf.
4. To upload new or changed inputs(tables, figures) to Overleaf, change it in the synced Dropbox directory. Users can replace the /paper_slides_issueXX/input/ folder in dropbox using the one in their local git project repo.
5. When ready to commit, User exports the content from Overleaf or synced dropbox folder to the local clone of the development branch manually, replace the files in original /paper_slides/code/ directory, and then commits.

Notice

1. Dropbox Synchronization is an Overleaf premium feature. Please make sure you have the subscription of Overleaf premium.
2. Dropbox sync does not have a brake/warning for file conflicts, so every user need to be very careful to (1) always instantly update the changes in /input/ both on github and dropbox-sync; (2) rebase collaborator's commit before updating to dropbox-sync.
3. Collaborators are suggested to modify .tex files only on the overleaf, because we don't commit our .tex changes until the end of issue.

Manage difference between Overleaf compile and local Tex compile

Overleaf uses the latest version of TexLive to compile, and users are allowed to shift to old TexLive versions. For details please refer to the official blog here. Lab-members need to set the TexLive version in local end consistent with the version in Overleaf to avoid seeing difference between the outputs. In some projects, co-authors might use a different TeX distribution (e.g., MiKTeX), to trying avoid compilation failure, lab-members should use the packages that only are part of the standard TeX distribution and specify old package versions in those projects.

Alternative workflow

The option proposed has some drawbacks referred here. If we expect the scope of issue is big and last for long time, this manual options require to upload inputs every time when there's new commit, and is vulnerable to potential failure points.

We then provide an alternative workflow using a mirror repository with automation, this is a Github Action solution of directly sync Overleaf to github issue branches without manual steps. Details can be referred in the attached PDF. This workflow requires a relative high fixed cost of setting up, and is not suggested to be a standard workflow for all issues.

mirror-repo-workflow.pdf