Collaboration Guide

Reasoning

Collaboration is a dynamic process that involves individuals with different approaches, perspectives, and working paces. To ensure a smooth and enjoyable collaboration experience, it is important to establish clear expectations and guidelines. This collaboration guide aims to provide all the necessary information to foster effective collaboration and minimize any potential surprises along the way.

Lines of communication

Open and effective communication is crucial for successful collaboration. My general style of communication is “ping-pong,” meaning I prefer short exchanges frequently. Here are some preferred lines of communication:

Email

Email serves as the primary mode of communication. Feel free to reach out to me at ondrej.mottl(at)gmail.com for any queries, updates, or discussions related to our collaboration. See ways to get in touch with me.

If you expect me to respond to your email, please state it clearly.

I strive to reply to all emails as soon as possible. However, there is a chance that I may have forgotten to answer yours. If I do not respond for a significant amount of time, feel free to send me a friendly reminder. 😊⏰

Other lines of communication

In addition to email, we can also utilize collaborative platforms such as Slack, Microsoft Teams, or any other platform that suits our needs. These platforms offer faster, real-time communication, which aligns well with the “ping-pong” style of interaction.

GitHub

Since my primary research involves writing code, GitHub is an essential platform for any collaborative work. Check out the overview of GitHub features to get familiar with its capabilities.

I love leveraging its features, such as Issues, Pull Requests, and Projects, to streamline our collaborative coding efforts. If you are not familiar with GitHub, don’t worry! I can provide guidance and support to help you get started. It’s worth checking out their documentation for more details.

Here is my basic GitHub workflow:

flowchart
    1["Make an Issue"] --> 2("Create a new branch")
    2 --> 351471["Commit code"]
    351471 --> 257387["Create Pull Request"]
    949464{{"Does it need a review?"}} --> 625480(["Yes"])
    949464 --> 564859(["No"])
    625480 --> 752396["Assign reviewer"]
    564859 --> 715681["Squash merge PR"]
    752396 --> 715681
    257387 --> 385770["Link the Issue"]
    715681 --> 688855("Close issue (if needed)")
    688855 --> 791180["Delete the branch"]
    385770 --> 515426("Add to Project (if <span>applicable</span>)")
    515426 --> 949464
    791180 -.->|"repeat"| 2

Here are the individual steps in detail:

1. Issues

An Issue represents a single task that needs to be addressed.

Each Issue provides a platform to communicate the task with a description and the possibility to discuss details using comments. An Issue should be related to a specific problem or task. If a task is too complex or large, the Issue can be divided into several smaller ones and linked using task lists.

For more details about Issues, refer to the GitHub documentation.

2. Branches

For any code change, a new branch should be created.

Each branch should correspond to a specific task (Issue). Therefore, a branch should be named to describe the problem it is solving or directly as issue[Issue number]. If you find that the problem is too complex and needs to be split into multiple Issues or branches, you can create another branch from the current one. Branches are lightweight, so don’t worry about creating many of them.

For more details about branches, refer to the GitHub documentation.

3. Writing code

Please follow the code conventions when writing code. Commit often but make sure to keep the description for each commit meaningful.

4. Pull Request (PR)

A Pull Request is a way to merge a branch into the main branch (or another branch). The PR name should clearly indicate the purpose of the changes.

The PR details should provide an explanation of the main modifications. Additionally, you can add comments to provide further context. If possible, create the PR as a “draft” until it is ready for review and merge (learn more about drafts).

As PRs are linked to branches, and each branch should be linked to an Issue, I prefer to use the “link” functionality explicitly. This can be achieved by mentioning the Issue with specific words (e.g., close) in the PR description (see more about linking).

If you want me to review your PR before merging, simply “assign” it to me (learn more about assigning).

I prefer to merge Pull Requests using the “squash merge commit” option (learn more about it here) for a cleaner git history.

5. Projects

GitHub Projects offer a new way of project management. If we agree to use a Project in our collaboration, we will define how to collaborate individually within that project framework.

Manuscript writing

Writing manuscripts is a crucial aspect of scientific collaboration. The most common tools for working on a manuscript are MS Word. However, to ensure consistency and efficient collaboration during manuscript preparation, I prefer to use Google Docs, which provides real-time collaboration, and simultaneous editing, and facilitates constructive feedback on the manuscript.

In any case, I prefer to make any edits via “suggestions”. However, note that I believe that it is absolutely fine to reject suggestions (or my suggestions to be rejected).