5  Collaboration

Effective collaboration and branch management are fundamental aspects of any successful software development project.

Key points:

  1. Identifying your collaboration needs: Understand the specific requirements of your project that necessitate collaboration.
  2. Setting up a contribution workflow: Establish clear guidelines for how contributors can participate in your project.
  3. Documenting the workflow: Ensure that your collaborative workflow is well-documented.

5.1 Collaborative workflow

Following the GitHub Flow model, everything starts from the main branch. Developers can create feature branches from the main branch to isolate their work. Once ready, changes are merged back to main.

A common workflow in a collaborative development project.

  1. Create a feature branch: Start by creating a new branch of the main project (usually called main or master). This branch should have a descriptive name to give an idea of the work that will be done, such as a new feature or a bug fix. This separation allows you to work independently without affecting the main codebase.
  2. Make changes and commit: Work on your branch, making the necessary changes to the code. Commit these changes with clear, descriptive messages.
  3. Open a pull request: Once you have made your changes, open a pull request (PR). During this step, your changes are reviewed before they are merged into the main branch. PRs allow for discussion, review, and additional changes if necessary.
  4. Review and deploy: Before merging, your changes might go through a review process where other team members can give feedback. Some projects may require a review before merging is allowed. After review, you might deploy your changes to a staging or testing environment to ensure everything works as expected.
  5. Merge: Finally, once your changes are reviewed and tested, you can merge the pull request into the main branch. This incorporates your contributions into the project, making them part of the official codebase.
  6. Delete feature branch: Feature branches should be short-lived, thus avoiding potential conflicts due to the divergence of the code.

sequenceDiagram
    participant A as Author
    participant R as Reviewer
    A->>A: Write some code in (forked) branch
    A->>R: Open a pull request
    R->>R: Add comments to a review
    R->>A: Submit a review
    loop Until approved
        A->>R: Address or respond to review comments
        R->>A: Clarify or resolve comments
    end
    R->>A: Approve pull request
    A->>A: Merge pull request
    A->>A: Delete branch

5.1.1 Forking

External collaborators who do not have the same administrative rights to the repository can fork the project. They make their changes on their forked repository in a new feature branch. Steps 3-5 remain the same.

Tip

You can create “Draft” Pull Requests. With Draft PR’s you - want to signal that a pull request is just the start of the conversation and your code isn’t in any state to be judged. - have no intention of ever merging it, but you’d still like people to check it out locally and give you feedback. - opened a pull request without any code at all in order to get the discussion started.

For more information, check out Introducing Draft Pull Requests.

5.1.2 Conflict resolution

Effective conflict resolution ensures that changes can be integrated smoothly and that the project remains on track. Conflicts occur when two or more changes compete with each other, typically during a merge or rebase operation in Git.

By utilizing pull requests code review and testing you can catch potential conflicts before they are merged into the main codebase.

Conflicts usually come up and are resolved during a pull request:

  1. Review Conflicts: When a conflict is detected in a pull request, GitHub will alert you. Start by reviewing the conflicting files to understand the nature of the conflict.
  2. Pull and Merge Locally: Fetch the latest changes from the main branch and attempt to merge them into your feature/develop branch locally. This will allow you to resolve conflicts on your local machine. Check status with git status and git diff.
  3. Resolve Conflicts: This might involve choosing one change over another or merging the changes manually.
  4. Test Changes: After resolving conflicts, thoroughly test your changes to ensure that the merged code works as expected.
  5. Commit and Push: Once conflicts are resolved and changes are tested, commit the resolved conflicts and push your changes back to the feature/develop branch on GitHub.
  6. Complete the Pull Request: After resolving conflicts and pushing your changes, review the pull request again to ensure everything is in order. If all checks pass and your team approves the changes, you can complete the merge into the main branch.

Essentially, the key to conflict resolution is avoiding them, and clear communication and adherence to established practices is the way to go.

Further reading