Project Management

Project Management#

 

The process of planning, executing and closing a project within a defined timeline and budget.

In this course, we will focus on transcribing this very general definition into the context of and its remote services, more precisely GitHub and GitLab.

+ Remote Tools Interactions#

 

With we posses a powerful tool to structure how we develop the content of a repository. Tools like Issues and Merge/Pull Request, provided by remote services, allow us to extensively document and track activities around any sort of plans, ideas, issues (not an Issue!), questions and suggestions. What we are still missing is how events and actions in relate to events and actions within these remote tools, and vice-versa.

As a start, let’s simply clarify that:

Some remote services can trigger actions in based on events & actions within their collaboration tools, and vice-versa.

For GitHub and GitLab there are many such triggers and it is not the goal here to provide a list of them. However, we would like to point out, that these triggers generally aim to synchronize the life-cycle of typical workflows. For example, pushing a new branch to the remote server will trigger the suggestion to create a Merge/Pull Request. Or merging one branch into another will close any open Merge/Pull Requests that has the branch as source branch and the other as target branch.

Even though remote services implement triggers in both directions, the underlying purpose of such triggers is clearly to position tools like Issues and Merge/Pull Requests as interfaces capable to reflect events and abstract some operations.

In doing so, remote services integrate typical workflows, like creating or merging a branch, into project management workflows performed with their collaboration tools.

Feature Branch Approach - reloaded#

Now that we know some of the Collaboration Tools remotes services provide, we can revise the ✨Feature✨ Branch Approach from our course working-with-git.

Let us quickly recall that a “Feature Branch” is a branch dedicated for the implementation of a distinct functionality, attribute, or similar and it should be intuitively clear that a collaborative context requires some form of documentation for the feature itself and ideally for the process of its implementation, as well.

Issues and Merge/Pull Requests are ideal tools to provide a standardized workflow for the feature branch approach.

In addition, some remote services also provide contextual triggers between some of their collaborative tools and the associated repository (and vice-versa), setting up a context in which:

The life-cycle of a feature branch can be managed entirely through the remote service.

Workflow#

GitLab

Allows steps 2 and 3 to be performed simultaneously.

1. Create an Issue 📝#

  • Identify the Feature: Start by identifying the feature you want to develop.

  • Check for similar Issues: It is always a good practice check for existing Issues; there’s no need to create duplicates if an identical or similar Issue already exists.

  • Formulate the Issue: Include details:

    • Description of the feature

    • Acceptance criteria

    • Any relevant design mockups or specifications

    • Priority and estimated effort

    • If it is a bug, include steps to reproduce and state the expected behavior

2. Create a Feature Branch 🌿#

  • Branch from the healthy reference: Create a new branch from the relevant healthy reference (e.g., main or develop). Name the branch descriptively, using a convention like feature/issue-number-description (e.g., feature/123-add-login-functionality).

    Note

    Remote services might offer to directly create a branch with a descriptive name that will allow linking the branch with the Issue.

    GitHub

    Offers to create a branch or link an existing Pull Request. The option to create a related Pull Request is postponed to the first commit on the branch.

    GitLab

    From an opened issue it is possible to also directly create a Merge Request along withe a dedicated branch. When doing so, the Merge Request is created as a draft.

  • Switch to the Feature Branch: Check out the new branch in your local development environment.

3. Create a Merge/Pull Request 🔄#

  • Push the Branch: Once the feature is complete and tested, push the feature branch to the remote repository.

  • Formulate a Merge/Pull Request: Create a merge request (MR) or pull request (PR) on GitHub, GitLab, etc. In the MR/PR:

    • Reference the original issue (e.g., “Closes #123”) to link the feature to the issue.

    • Provide a description of the changes that you made and any relevant context.

    • Specify any additional reviewers or stakeholders.

    Note

    A common suggestion is to create a Merge/Pull Request after having implemented the feature (i.e. after 5. Test the Feature). We recommend to anticipate the creation of the Merge/Pull Request and to mark it as draft until the feature is implemented. In doing so you can use the “News Feed” of the draft Merge/Pull Request to document the development process.

4. Develop the Feature 💻#

  • Implement the Feature: Write the code to implement the feature as described in the issue.

  • Commit Changes: Regularly commit your changes with clear and descriptive commit messages that reference the issue number (e.g., “Fixes #123: Implement login functionality”).

5. Keep Branch updated 🔄#

  • Include changes from healthy reference: Regularly include any updates of the target branch. In practice this boils down to regularly either rebase the feature branch, or merge the target branch.

  • Check compatibility of changes: Make sure that any changes from the healthy reference branch are compatible with your implementation of the feature.

    Warning

    What state identifies as the healthy reference might change throughout the development of a feature. It is up to the developer to assert that merging a feature branch leads again to a healthy state. Thus, the feature branch must be compatible with the target branch by the time it is ready to merge, and not when it was created.

6. Test the Feature 🧪#

  • Local Testing: Test the feature locally to ensure it works as expected.

  • Update Documentation: If necessary, update any relevant documentation to reflect the new feature.

7. Code Review 👥#

  • Mark the Merge/Pull Request as ready: Remove the “draft” status from the Merge/Pull Request

    Note

    Usually the option is to be found in the News Feed of the Merge/Pull Request:

    GitHub

    Here the option is called Ready for review

    GitLab

    Here: Mark as ready

  • Review Process: Team members review the merge request, providing feedback and suggestions.

  • Make Revisions: Address any feedback by making necessary changes to the code and pushing updates to the feature branch.

8. Merge the Feature ✅#

  • Approval: Once the merge request is approved, merge the feature branch into the main branch.

  • Close the Issue: After merging, close the original issue to indicate that the feature has been completed.