<< ReproducibilityCourse

---

How to branch off your own version of a Maneage template

Make some changes and commit them locally

• Start with your directory set up of a research paper that already works, such as gevcurvest .
  1. Do ./project make to check that the pdf is still produced correctly.
  2. Make some changes. To start with, you can make some trivial edits. Once you're ready for more serious edits, scroll down.
  3. Test them and store a log file, just in case: ./project make |& tee log.2 if you want your log file to be called log.2
  4. If there's a failure:
     • investigate the log file, try to understand what went wrong. You have full control of all the plain text files of the full pipeline, so read and search through them using less, grep, and other related tools. If you're unfamiliar with less and grep, then try info less and info grep. Even if you're familiar with grep, you can probably learn some more, so try info grep anyway.
     • Try to tr * Start with your directory set up of a research paper that already works, such as gevcurvest .
  5. Do ./project make to check that the pdf is still produced correctly.
  6. Make some changes.
  7. Test them and store a log file, just in case: ./project make |& tee log.2 if you want your log file to be called log.2
  8. If there's a failure:
     • investigate the log file, try to understand what went wrong. You have full control of all the plain text files of the full pipeline, so read and search through them using less, grep, and other related tools. If you're unfamiliar with less and grep, then try info less and info grep. Even if you're familiar with grep, you can probably learn some more, so try info grep anyway.
     • Try to trace the bug yourself, but also ask on irc/matrix, email, by reading the README* files, and by looking at Maneage Support, Bug and Task trackers.
     • Also ask the lecturer for help ;).
  9. If there's no failure, or after fixing the bug:
     • Start or improve your knowledge of git with: man gittutorial
     • Create your own branch in a logical sense e.g. git branch mybranch
     • Change your logical location (in the git sense) to your own branch: git checkout mybranch
       • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution.
     • Commit any modified files with e.g. git commit -a
       • If you don't like the default editor, then set your git config editor, e.g. with git config --get core.editor to check your current editor, and git config --set core.editor 'emacs -nw' if you want your editor to be emacs -nw
     • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution. You should see that your commit is in the mathematical graph of the evolution of the set of files.ace the bug yourself, but also ask on irc/matrix, email, by reading the README* files, and by looking at Maneage Support, Bug and Task trackers.
     • Also ask the lecturer for help ;).
  10. If there's no failure, or after fixing the bug:
      • Start or improve your knowledge of git with: man gittutorial
      • Create your own branch in a logical sense e.g. git branch mybranch
      • Change your logical location (in the git sense) to your own branch: git checkout mybranch
        • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution.
      • Commit any modified files with e.g. git commit -a
        • If you don't like the default editor, then set your git config editor, e.g. with git config --get core.editor to check your current editor, and git config --set core.editor 'emacs -nw' if you want your editor to be emacs -nw
      • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution. You should see that your commit is in the mathematical graph of the evolution of the set of files.

What changes should you make?

Delete the core old stuff

Commit 7ea27bd3 on the reproducibility-course-how branch shows an example of deleting the core old stuff. It should give you a nice simplified pdf.

• Remove the current workflow - the science steps of the sequence - except for the beginning and end:
  • To do this, edit the makesrc definition of reproduce/analysis/make/top-make.mk (This is what is currently written as Add `XXXXXX`, as a new line, to the values in `makesrc` of the top-level `Makefile`. in README-hacking.md .)
  • WARNING: Use editor settings that conserve tab characters, i.e. that do not convert them to spaces. The initial tab in the lines of a make rule is crucially important.
  • Remove the strings init-N-body , run-simulations and analyse-plot from the definition of makesrc
• Disable verification of the results of the project, because we're making a fresh project:
  • Edit the reproduce/analysis/conf/verify-outputs.conf - remove "yes"
• Now try ./project make |& tee log.3 . * This will fail, because the removal of the analyse-plot.mk step implies that the output file .build/analysis/tex/macros/analyse-plot.tex is ignored.
• Edit paper.tex removing most of the main content that is not yours. Leave in some content as temporary examples, and put some markers such as \textbf{NOTMYSTUFF} on content that you leave in place so that you don't accidentally leave it in place in your own paper.
  • Try ./project make |& tee log.4 and do fixes to paper.tex until you again can produce a very minimal template pdf.

Add some minimal new stuff

Commit 611cb9e53 on the reproducibility-course-how branch shows an example of adding some minimal new stuf. It should give you a nice simplified pdf that now shows a result from a simple calculation in the abstract.

• Do git log --stat to read the commit description describing the changes:
  • A new makefile examplemake.mk was added.
  • examplemake was added to top-make.mk
  • paper.tex was edited to include the TeX string \FinalResult
• You will need to learn something about several of the powerful shell tools that you have available using info COMMAND and experimenting, or if you like,
  • WikipediaEn:make%20%28software%29
  • WikipediaEn:sed
  • WikipediaEn:tr%20%28Unix%29
  • WikipediaEn:AWK
  • WikipediaEn:printf%20%28Unix%29

-- BoudRoukema - 01 Apr 2025, 08 April 2025+