{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Use GitHub to Collaborate on Open Science Projects\n",
        "\n",
        "Leah Wasser  \n",
        "Jenny Palomino  \n",
        "Max Joseph\n",
        "\n",
        "## **GitHub** for Collaboration\n",
        "\n",
        "**GitHub.com** is a website that supports version control using git. In\n",
        "this chapter, you will learn how to use **GitHub** for both version\n",
        "control and as a collaboration tool. Specifically, you will learn about\n",
        "a well-known and used collaboration model that is used in the open\n",
        "software community.\n",
        "\n",
        "After completing this chapter, you will be able to:\n",
        "\n",
        "-   Explain the difference between **git** and **GitHub**.\n",
        "-   Describe the open source software collaboration model as it is\n",
        "    implemented on **GitHub**.\n",
        "-   Explain what a pull request (PR) is and how PRs are used on\n",
        "    **GitHub**.\n",
        "-   Create a pull request in **GitHub**.\n",
        "-   Explain what a **GitHub** issue is and explain how issues are used\n",
        "    on **GitHub**.\n",
        "-   Create an issue in **GitHub**.\n",
        "\n",
        "You will need a web browser and a **GitHub.com** login (username and\n",
        "password).\n",
        "\n",
        "## Why Use GitHub For Science Collaboration?\n",
        "\n",
        "In the previous chapter, you learned about **git** and **GitHub**.\n",
        "Recall that **git** is a tool that is used to manage version control for\n",
        "various files. **GitHub.com** is a website that runs **git** behind the\n",
        "scenes.\n",
        "\n",
        "The **GitHub.com** website also has additional functionality that\n",
        "extends the functionality of **git**. This functionality allows you to\n",
        "manage projects and coordinate with others on updates to code, text\n",
        "files, and other files in your repo. **GitHub** also facilitates sharing\n",
        "your code with the world (OR with specific people if you need to work\n",
        "with a smaller group of people privately).\n",
        "\n",
        "In the next few lessons, you will learn more about the various\n",
        "**GitHub** tools that you can use to collaborate on projects.\n",
        "\n",
        "## GitHub For Project Management and Collaboration\n",
        "\n",
        "There are several tools that **GitHub** offers that you can use to\n",
        "support collaborating on projects.\n",
        "\n",
        "### 1. GitHub Pull Requests\n",
        "\n",
        "A pull request is a way that you or a colleague can suggest code changes\n",
        "to a repository.\n",
        "\n",
        "A pull request allows: \\* Your collaborators to see exactly what items\n",
        "were changed line by line in the code. \\* A group of people working on\n",
        "the code to view, review and comment on the code line by line. \\* You to\n",
        "document changes to your project which can also be clearly linked to\n",
        "issues that describe the need for those changes (see below).\n",
        "\n",
        "The pull request is a great way to ensure that everyone is on the same\n",
        "page with your edits before the changes are merged or combined into the\n",
        "designated repository.\n",
        "\n",
        "Pull Requests are specific to the **GitHub** website."
      ],
      "id": "f7473986-a2d3-4df6-bd59-f1007711d140"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figure>"
      ],
      "id": "f379d954-876a-4bac-916a-c6668e4ca291"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<a href=\"{{ site.url }}/images/earth-analytics/git-version-control/github-diff-file.png\">\n",
        "<img src=\"{{ site.url }}/images/earth-analytics/git-version-control/github-diff-file.png\" alt=\"This screenshot shows a diff (i.e. difference between two files) associated with a pull request. On the LEFT, you can see the text (highlighted with red) that was modified by the proposed pull request. The words that are dark red were the ones that were deleted. On the RIGHT, you can see the text (in green) that represents the proposed changes. The words that are darker green were added. In this example, the word **earthpy** was replaced with **matplotcheck** in the contributing.rst file of the repo\"></a>"
      ],
      "id": "0a76c80f-ca57-47a8-bb13-f49ec12513d5"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figcaption>"
      ],
      "id": "d1853ec7-0407-4afd-971b-5134ff1639c3"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This screenshot shows a diff (i.e. difference between two files)\n",
        "associated with a pull request. On the LEFT, you can see the text\n",
        "(highlighted with red) that was modified by the proposed pull request.\n",
        "The words that are dark red were the ones that were deleted. On the\n",
        "RIGHT, you can see the text (in green) that represents the proposed\n",
        "changes. The words that are darker green were added. In this example,\n",
        "the word **earthpy** was replaced with **matplotcheck** in the\n",
        "contributing.rst file of the repo."
      ],
      "id": "55829fb5-bba0-48ae-8814-3f8ed1e7d120"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figcaption>"
      ],
      "id": "75c1a777-7962-4f3f-b91a-acc82262db35"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figure>"
      ],
      "id": "2884d63e-070e-4175-b61e-61209645cb7f"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 2. GitHub Issues\n",
        "\n",
        "Issues in **GitHub** are ways to document and discuss changes needed in\n",
        "a repository. Issues are also ideal for managing changes in a project.\n",
        "\n",
        "Issues are normally text (and code) that describe something that needs\n",
        "to be addressed in the repository. An issue could be related to\n",
        "something that needs to be fixed in your code or text.\n",
        "\n",
        "Issues can be assigned to one or more people to work on which makes them\n",
        "useful for project management. You can keep track of who is working on\n",
        "what items in the repository.\n",
        "\n",
        "Once an issue is defined (with requested changes to the code in your\n",
        "repo), you can then assign it to someone. At that point, you have\n",
        "documentation of who is working on what task. Finally, when the person\n",
        "assigned an issue submits a pull request to address that issue, they can\n",
        "link the pull request back to the original issues.\n",
        "\n",
        "If you are familiar with IT (Information Technology) groups or computer\n",
        "help desks, this is similar to submitting a ticket, except for this\n",
        "ticket can be created collaboratively.\n",
        "\n",
        "Linking issues to pull requests is good practice and will be discussed\n",
        "in more detail later in this chapter."
      ],
      "id": "2fbc65d5-cb94-4849-9493-7335c9641e9f"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figure>"
      ],
      "id": "6a0f2889-1a56-4918-a662-84ebbbe33d84"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<a href=\"{{ site.url }}/images/earth-analytics/git-version-control/git-push-pull-flow.png\">\n",
        "<img src=\"{{ site.url }}/images/earth-analytics/git-version-control/git-push-pull-flow.png\" alt=\"In a GitHub workflow, there is often a central repository. This is where the code or content maintainers keep the most up to date and 'live' versions of the code. Changes are suggested by users using a pull request workflow where someone makes changes in a fork and then suggests that the maintainers add those changes to the central repository using a pull request. Source: Colin Williams, NEON\"></a>"
      ],
      "id": "730e719f-5666-458c-a3bb-d95fa79f3fe2"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figcaption>"
      ],
      "id": "cfc32f32-3efc-48f1-a752-c053db60ded1"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In a GitHub workflow, there is often a central repository. This is where\n",
        "the code or content maintainers keep the most up to date and ‘live’\n",
        "versions of the code. Changes are suggested by users using a pull\n",
        "request workflow where someone makes changes in a fork and then suggests\n",
        "that the maintainers add those changes to the central repository using a\n",
        "pull request. Source: Colin Williams, NEON"
      ],
      "id": "84aab5b1-1c21-412c-8534-d964bacdd8c6"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figcaption>"
      ],
      "id": "61ef245e-282d-45bc-9e35-2dc8ed2ce2f5"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figure>"
      ],
      "id": "de9a30f3-8ba5-4e35-bdb7-55e9226418b4"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 3. GitHub Project Milestones\n",
        "\n",
        "There are other project management tools within **GitHub** that you can\n",
        "use to manage your project as it becomes more complex, including\n",
        "milestones and even Trello like project boards.\n",
        "\n",
        "If you are working on a large project, you can create milestones which\n",
        "can be used to group sets of related issues together. Milestones can\n",
        "have deadlines associated with them."
      ],
      "id": "70db28ae-e380-4ad9-8d8b-81c8f1db5d9a"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figure>"
      ],
      "id": "8b439bf2-e534-4bf3-a876-3eb121b194ab"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<a href=\"{{ site.url }}/images/earth-analytics/git-version-control/github-milestones-abc-classroom.png\">\n",
        "<img src=\"{{ site.url }}/images/earth-analytics/git-version-control/github-milestones-abc-classroom.png\" alt=\"GitHub milestones allow you to track smaller sets of tasks within a larger GitHub project.\"></a>"
      ],
      "id": "0878f96a-680d-4732-b769-d43c20c521b3"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figcaption>"
      ],
      "id": "bd63b97a-51f7-4acb-baa0-b001c1463274"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "GitHub milestones allow you to track smaller sets of tasks within a\n",
        "larger GitHub project."
      ],
      "id": "a6a23b0f-2edd-4a40-9887-69111d5b98df"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figcaption>"
      ],
      "id": "3e0074eb-e21d-4476-8050-34b7ea15bd24"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figure>"
      ],
      "id": "1672ca36-d6c8-4fda-af38-65abb35a2da5"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### 4. **GitHub** Project Management Tools\n",
        "\n",
        "You can also use **GitHub** to manage an entire project or set of\n",
        "projects. You can setup boards similar to a tool like Trello to manage\n",
        "pull requests and milestones, who is working on what and associated\n",
        "deadlines.\n",
        "\n",
        "These more advanced **GitHub** project management tools are not\n",
        "discussed in this chapter, but you are encouraged to check them out if\n",
        "you are interested in using **GitHub** to manage your open science\n",
        "projects."
      ],
      "id": "48ea18ef-586e-4429-97f1-92957ce573fb"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figure>"
      ],
      "id": "de27f6a9-9bb1-485e-983b-2913d2b7f187"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<a href=\"{{ site.url }}/images/earth-analytics/git-version-control/github-project-page.png\">\n",
        "<img src=\"{{ site.url }}/images/earth-analytics/git-version-control/github-project-page.png\" alt=\"GitHub allows you to track projects across a single repository OR across all of the repos in your organization or account.\"></a>"
      ],
      "id": "1728065b-0228-4c10-be37-9f4342d22c06"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figcaption>"
      ],
      "id": "3a1b370e-bf5a-42aa-a562-1a6b3ad069f1"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "GitHub allows you to track projects across a single repository OR across\n",
        "all of the repos in your organization or account."
      ],
      "id": "3017b97c-07d7-43b3-a8ae-1f406ccb340d"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figcaption>"
      ],
      "id": "3b82aae8-6c78-4685-bfb7-ed2d2d4889c0"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figure>"
      ],
      "id": "a702912e-5284-4e8a-8d92-7a10876d4b48"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Putting It All Together: the Open Source Collaboration and Project Management Model\n",
        "\n",
        "### GitHub Issues and Pull Requests\n",
        "\n",
        "Over the course of this chapter, you will learn how to put together all\n",
        "of the pieces of the pull request workflow. To break it down, it looks\n",
        "something like this:\n",
        "\n",
        "1.  Individuals within your team identify issues that need to be\n",
        "    addressed.\n",
        "2.  Someone (likely the owners of the repository) assigns team members\n",
        "    to work on specific issues.\n",
        "3.  Team members work on their individual tasks.\n",
        "4.  When they are ready to suggest changes, team members submit a pull\n",
        "    request (PR) to the main repository. That pull request is reviewed\n",
        "    by team leaders (or whomever is assigned to review).\n",
        "5.  The reviewers may suggest changes to the code. If so, the PR\n",
        "    submitters go back and work on the code some more. This process may\n",
        "    continue until everyone is happy with the PR.\n",
        "6.  When the PR is approved by the reviewers, it will be merged into the\n",
        "    code base of the repository.\n",
        "\n",
        "All of the above steps may be repeated over and over through time, as\n",
        "issues are identified and contributors submit changes.\n",
        "\n",
        "This is the open source collaborative software workflow and a workflow\n",
        "that many use to manage **GitHub** projects in general."
      ],
      "id": "66c49468-8e9c-4585-b5f8-009429126d85"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figure>"
      ],
      "id": "bbe53307-b61d-4816-905f-f6aaf709833d"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<a href=\"{{ site.url }}/images/earth-analytics/git-version-control/overview-github-collaboration.png\">\n",
        "<img src=\"{{ site.url }}/images/earth-analytics/git-version-control/overview-github-collaboration.png\" alt=\"GitHub supports collaboration across multiple users working on related tasks within one repository. One way that GitHub supports this collaboration is through the use of forks (i.e. copies of a central repository that each user can use to work independently on tasks). After work is completed in a fork, a user can request to have their changes applied to the central repository using a pull request. Source: Earth Lab, Alana Faller\"></a>"
      ],
      "id": "e95f725e-aceb-4966-a2ff-3c25ded881d7"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "<figcaption>"
      ],
      "id": "eaf5653e-92e6-4348-9751-07e9031fd8ef"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "GitHub supports collaboration across multiple users working on related\n",
        "tasks within one repository. One way that GitHub supports this\n",
        "collaboration is through the use of forks (i.e. copies of a central\n",
        "repository that each user can use to work independently on tasks). After\n",
        "work is completed in a fork, a user can request to have their changes\n",
        "applied to the central repository using a pull request. Source: Earth\n",
        "Lab, Alana Faller"
      ],
      "id": "e9de4e48-1ca2-41d5-99a1-71426d037db8"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figcaption>"
      ],
      "id": "f85cde63-5006-491e-81f9-6ecbb6eeeafa"
    },
    {
      "cell_type": "raw",
      "metadata": {
        "raw_mimetype": "text/html"
      },
      "source": [
        "</figure>"
      ],
      "id": "c9ebbe33-5c83-4cfa-871d-2f864b9a9bcd"
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In this chapter, you will first learn about and practice submitting pull\n",
        "requests to update repositories. In the second half of the chapter, you\n",
        "will be exposed to the full open source collaboration workflow,\n",
        "including the use of issues."
      ],
      "id": "57481916-bb1d-4561-9dbe-7285ac697dd3"
    }
  ],
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {
    "jupytext": {
      "cell_metadata_json": true,
      "formats": "ipynb,md"
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3",
      "language": "python"
    },
    "language_info": {
      "name": "python",
      "codemirror_mode": {
        "name": "ipython",
        "version": "3"
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.10.17"
    }
  }
}