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
Collaborating on Word documents (without Git versioning)
Create Shared Cloud Folder: Use cloud platforms like Dropbox or GoogleDocs for easy access to the latest version (or real-time collaboration).
Distribute Tasks: Assign specific sections to team members (e.g., introduction, methods, conclusion) or avoid parallel work to prevent overwriting changes.
Use Track Changes: Enable “Track Changes” for transparency in edits and feedback, and resolve comments to keep the document clean.
Create Versions: Save incremental versions of the document (e.g., paper_v1.docx, paper_v2.docx) to ensure progress is tracked.
Decide on Reference Manager: Choose a reference manager (e.g., Zotero, Mendeley) and plugin for consistent citation formatting and easy management of references.