20.16 Collaboration

Table of contents

Git-based collaboration

TODO : this will contain best practices and Git commands

gitGraph TB:
   commit id: "setup"
   commit id: "research_objectives"
   branch author_2
   branch author_3
   checkout author_2
   commit id: "methods_draft"
   checkout main
   merge author_2
   checkout author_3
   commit id: "data collection"
   commit id: "analysis"
   checkout main
   merge author_3
   commit id: "paper draft"
   commit id: "finalize paper" tag: "submission" type: HIGHLIGHT

gitGraph TB:
   commit id: "finalize paper" tag: "submission" type: HIGHLIGHT
   commit id: "revision_sheet"

   branch author_2
   branch author_3
   checkout author_2
   commit id: "address issue_1"
   commit id: "write response"
   checkout main
   merge author_2
   checkout author_3
   commit id: "address issue_2"
   checkout main
   merge author_3
   commit id: "complete revision"

Changes are tracked by the collaborative versioning system git. Tutorials on git are available online (1, 2).

Contributing changes

  • Check the git-diff (gitk) before committing changes.
  • Use the following commit message format (do not start commit message with #3):
git commit -m 'address limitations [iss28]'
  • Commit minor changes directly to the polishing branch, use dedicated branches otherwise (especially when changes need to be discussed in a pull-request).
  • Create a single branch for issues that are related (e.g., group all issues referring to the introduction in the branch update_introduction).
  • Example:
git switch main
git checkout -b iss12
  • While working locally on the iss12, rebase it on main when the main branch has been updated by coauthors (for better management of the history):
git switch iss12
git rebase main
  • Once the branch is ready for review, revisions, and merging, share it:
git push iss12
# set the upstream branch as suggested
  • Do not rebase shared branches while working on it.
  • Discuss, revise and merge on shared branches (github.com).
  • Merge when changes have been confirmed:
git switch main
git merge --squash iss12
git push

Retrieving changes from coauthors

  • Check out remote branch:
git switch -c iss12 --track origin/iss12
  • When your repository has local changes (commits): pull-rebase to avoid unnecessary merge commits:
git pull --rebase
  • When your repository has local changes (uncommitted): stash and pull-rebase:
git stash
git pull --rebase
git stash apply

Git-based collaboration with Word users

Whenever possible, ask active coauthors to modify the paper.md file.

Otherwise:

  • To share: create a commit with the latest changes.
  • Export paper as word file.
  • Filename: increment the version number with every docx file that is shared externally (example: Manuscript_v11.docx).

  • For you own reference, you may store the same file in a local directory, including the hash-id of the latest commit as the second part of the filename (example: Manuscript_v11 d091j209fs8.docx). This can be useful to track the mapping between version numbers and the corresponding hash-id (git history).

  • When receiving feedback in the docx: always make sure that feedback (including tracked and untracked changes) is transferred to the paper manually.
    • Create PDF from word with tracked changes (it is important to know which ones have/have not been addressed rather than having a Word-file in which all changes have been accepted/issues addressed - this is done in the paper.md.).
    • While addressing the comments: highlight suggestions that have been addressed in green (strike out suggestions that will not be addressed), and possibly provide comments on how issues have been addressed (why this way?).
    • Typos and very minor comments: address in one commit (e.g., “fix spelling errors”)
    • Other comments: address in individual commits (possibly including the comment-ids generated by the word-to-pdf export in the commit message)
    • Major issues: include in the readme.md (possibly discuss with coauthors) and address in a separate branch

Word-based collaboration

TODO

Resources