Add Overleaf workflow to wiki

[ShiqiYang2022]

Follows gentzkow/template_archive#84 (comment) and gentzkow/template_archive#87 (comment).

In this issue we will add the workflow of Overleaf to lab-manual Wiki appendix. For projects compiling .tex, we want to (1) provide instructions to allow Overleaf workflow on development(issue) branches; (2) Manage the difference for Overleaf & Local .tex compile properly.

[ShiqiYang2022]

A proposed draft is attached:

Proposed Draft

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

[ShiqiYang2022]

Hi @gentzkow, see the proposed draft above of revised workflow after the decision in gentzkow/template_archive#87 (comment). I plan to add this to [Wiki]-[Appendix]-[Overleaf workflow].

Let me know for your thoughts of proposed draft, thanks!

cc: @jmshapir

[gentzkow]

Great. Thanks! Let's add this as an appendix of the RA manual and link it from the Papers & Slides page (similar to what we do for the autofilling page).

No need to copy @jmshapir here -- he has now separated his version of the RA manual out into a separate fork.

[ShiqiYang2022]

@gentzkow Thanks! I just added the workflow to the appendix wiki, and linked to Paper & Slides.

I am closing this issue now as I think the goal of this issue has been achieved.

[ShiqiYang2022]

Summary

In this issue we add the Overleaf Workflow to the appendix of lab-manual wiki. The link to the workflow page is here.