An Example Workflow

You have just received an assigment email about package JPE-Oswald-66666666. You have carefully read it. Now what?

First Round or Subsequent Round?

There is a distinction between first round and subsequent round packages. On your git repo, each round is a different branch. That is, when you clone this for the first time, you see that you have branch round1. How to see this? 👇

git branch

👉 Watch out in the git operations below.

1 Package Acquisition

Get or update repo:

If this is the first round, clone the git repo (using url in your email - here I use an example package) to your computer. For example to ~/JPE-replications. That would be
```
cd ~/JPE-replications
git clone https://github.com/JPE-Reproducibility/JPE-Oswald-66666666.git
```

If this is subsequent round n, say n=3, you just have to get the next round branch:

cd ~/JPE-replications/JPE-Oswald-66666666
git branch -r  # check which remote branches are available
git checkout -b round3 origin/round3 # creates local branch round3 from remote branch round3

Download dropbox folder with full package and paper. That’s the second URL in your email.
Extract package (if compressed), and copy into the git repo as ~/JPE-replications/Author-1234/replication-package

Danger Zone ⛔️

Do not copy the replication package anywhere else on your computer (maybe because you are uncomfortable with git). Copying files back and forth manually on your computer is a recipe for assured disaster - don’t go there.

2 First Compilation of report

Before doing anything else, open VScode at ~/JPE-replications/JPE-Oswald-66666666.
Open file TEMPLATE.qmd
Hit Shift-Cmd-K or open command palette and type quarto: preview
You will see the template I prepared for this round of the package. Make sure it looks ok and all my prepared content shows up.

3 Doing the Replication and Preparing Report

Start working on the job, by going through TEMPLATE.qmd and make edits as required.

It Does Not Work

What if there are issues with running the package?

If there is an obvious bug, this just goes into your report. If reasonably quick to do, try to fix the bug in the code, and run with your fix. Obviously you should commit your changes to the code to the repo with suitable comments. Your report should contain a very precise description of the bug and your solution.
If you need help figuring out the details of the problem (if you are unsure whether this actually a bug or something you might be doing wrong): Then file an issue on the github repo of your package and ping @jpedataeditor in your issue description. Do not write on slack about the bug in the first place.

4 Submitting report

This again differs by whether first or subsequent round.

First round:

git add package-output-map.xlsx
git add images # for your screenshots
git add TEMPLATE.qmd  # your edits
git add TEMPLATE.pdf  # the compiled version of your report
git add TEMPLATE.html  # or in html
git add TEMPLATE-APPENDIX.qmd  # if you made any edits
git commit -m 'first round report. code breaks. missing citations.'
git push origin round1  # pushes back to `round1` branch - this must be the branch you cloned from, don't create a new branch!

round n:

Let’s say again that n=3.

git add package-output-map.xlsx
git add images # for your screenshots
git add TEMPLATE.qmd  # your edits
git add TEMPLATE.pdf  # the compiled version of your report
git add TEMPLATE.html  # or in html
git add TEMPLATE-APPENDIX.qmd  # if you made any edits
git commit -m 'round 3 report. almost done. still missing citations.'
git push origin round3  # pushes back to `round3` branch