Skip to content

[Feb 4 merge] Review GitHub lessons 0-3 #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Feb 4, 2025
Merged

[Feb 4 merge] Review GitHub lessons 0-3 #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d5b7cd5
Delete for review
lwasser Jan 21, 2025
04997b2
Fix: current lesson state + Jeremy's feedback
lwasser Jan 31, 2025
8be1778
Fix: reorg page
lwasser Jan 31, 2025
ae4d510
add: fork repo image
lwasser Jan 31, 2025
7dcdf67
remove old file
lwasser Feb 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 16 additions & 26 deletions github-git/edit-commit-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Now that you've [identified and comment on an issue](identify-issue), [forked th

:::{admonition} What you'll learn
:class: tip
You’ll edit a file directly in your **fork** using GitHub’s interface and commit the changes using only the native GitHub interface.
You’ll edit a file directly in your **fork** using GitHub’s interface and commit the changes using only the native GitHub interface.

NOTE: If you want to work on the files locally on your laptop, you will need to [clone or make a copy of your repo locally](clone-repo).

Expand All @@ -50,21 +50,20 @@ Editing a file directly in the GitHub interface is a straight forward process.
> **⚡ Quick tip:** You can edit as many files as you want, but GitHub only lets you commit them **one at a time** in the browser.


## Editing files directly on GitHub vs. GitHub Codespaces
## Ways to edit a file: GitHub vs. GitHub Codespaces

GitHub now offers **two ways** to edit files directly in the interface or using the cloud based GitHub Codespaces:
GitHub now offers **two ways** to edit files directly in the interface or using the [cloud-based GitHub Codespaces](about-codespace). If you’re making a small change, use GitHub’s interface. If you need to edit multiple files, try Codespaces.

| Option | When to Use | Pros | Limitations |
|---------|------------|------|-------------|
| **GitHub Interface** <i class="fa-solid fa-pencil" style="color: #81c0aa;"></i> | Quick edits (typos, small fixes) | No setup needed, edit in browser | Can only commit one file at a time |
| **GitHub Codespaces** <i class="fa-solid fa-laptop-code" style="color: #81c0aa;"></i> | Editing multiple files | Full VS Code environment in browser | Requires configuration but once configured, you can reuse it |
| | Option | When to Use | Pros | Limitations |
|-|---------|------------|------|-------------|
| | **GitHub Interface** <i class="fa-solid fa-pencil" style="color: #81c0aa;"></i> | Quick edits (typos, small fixes) | No setup needed, edit in browser | Can only commit one file at a time |
| | **GitHub Codespaces** <i class="fa-solid fa-laptop-code" style="color: #81c0aa;"></i> | Editing multiple files | Full VS Code environment in browser | Requires configuration but once configured, you can reuse it |

> **💡 Need to edit multiple files using a coding editor like VsCode or Jupyter?** Learn more about using [GitHub Codespaces](github-codespaces).


## What is a commit?

You can think of a **commit** as a save (or restore) point in git version control's history. Each commit captures changes that you make to one or more files in the repository at a specific point in time; each commit includes a note explaining what you did.
A commit is like taking a snapshot of your changes so you can always "undo" the changes if needed. You can think of a **commit** as a save (or restore) point in git's history. Each commit captures changes you make to one or more files in the repository at a specific time; each commit includes a note explaining what you did.

:::{tip}
A **commit** is a feature of [git version control](what-is-git), the version control system that GitHub runs in the background.
Expand All @@ -88,27 +87,18 @@ Each commit represents **a set of changes** at a specific time.
You can always **undo or revert** changes using Git.
:::

## Up next: Make a pull request
:::{admonition} What's next?
:class: seealso

Once you've committed your changes, you can open a **pull request (PR)** to suggest your edits to the main project.
<i class="fa-brands fa-github-alt"></i> Once you've committed your changes, you can open a **pull request (PR)** to suggest your edits to the main project.

[Learn how to create a pull request →](pull-request)
*****

[Learn how to create a pull request →](pull-request)
:::


:::{todo}

It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too from the community that we could share with some stories about it??


Github has changed things a bit. If you edit the file in place, it automatically directs you to a pr workflow in the repo that you are in.

So I think we want to break this down into two things

1. The drive-by pull request

* Click on the edit button in the repo that you want to make changes.
* If you don't have permission, it will automatically ask you about making a branch, which will be from your fork.

2. The pr from your fork. If the fork already exists, then you can still edit the file.

It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples from the community that we could share some stories about.
:::
129 changes: 99 additions & 30 deletions github-git/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,62 +9,131 @@ kernelspec:
display_name: Python 3 (ipykernel)
language: python
name: python3
myst_html_meta:
"title": "Intro"
"description lang=en": "More"
"keywords": "GitHub, OpenSource"
"property=og:locale": "en_US"
---

# Use GitHub With Friends
# Introduction to GitHub and Open Source Collaboration

:::{todo}
This might belong in the background section.
:::
GitHub is a **social coding platform** that allows individuals and teams to manage, track, and collaborate on software projects. It plays a key role in **open source development**, enabling contributors worldwide to work on, improve and maintain code and documentation together.

GitHub is a social coding platform.
GitHub can be used in two primary ways: **independently** or **collaboratively**.
> This guide covers:
> <i class="fa-solid fa-circle-check" style="color: #81c0aa;"></i> What GitHub is and how it supports **open source communities**
> <i class="fa-solid fa-circle-check" style="color: #81c0aa;"></i> How GitHub is used for **both solo work and collaborative projects**
> <i class="fa-solid fa-circle-check" style="color: #81c0aa;"></i> The difference between **personal vs. team workflows**

## Use GitHub by yourself
## GitHub and open source

Most scientists start using GitHub (and git) on their own. In this scenario, Git is a personal version control system, enabling you to track changes and maintain a complete work history. Working on your own is ideal for personal projects, preliminary research, or prototyping, as it allows you to revert to earlier versions if needed.
**Open source software (OSS)** is code that is publicly accessible—anyone can view, modify, and distribute it. GitHub provides the tools needed for open source projects to store code publically, manage contributions, track and address issues, and collaborate efficiently.

If you are using GitHub on your own, your workflow probably looks something like this:
Specifically, in the Python language, the software is often [associated with packaging](https://www.pyopensci.org/python-package-guide/tutorials/intro.html), where you package up code and make it easier for a user to install on their computer. Reusable sofware allow developers and scientists to share common workflows rather than needing to recreate the code needed for each workflow themselves from scratch.

1. **Clone a Repository**: Copy the project to your local computer.
2. **Work Locally**: Edit files and make changes on your machine.
3. **Commit Changes**: Save your changes to the project history.
4. **Push Changes**: Upload your updates to GitHub as a backup.
### Why open source communities use GitHub

:::{figure} /images/github/use-github-yourself.png
:alt: Alt here
- **<i class="fa-solid fa-globe" style="color: #81c0aa;"></i> Global collaboration**: Developers from around the world can contribute.
- **<i class="fa-solid fa-code-branch" style="color: #81c0aa;"></i> Version control**: Track every change made to the project.
- **<i class="fa-solid fa-comments" style="color: #81c0aa;"></i> Transparent discussions**: Use issues and pull requests to propose and review changes.
- **<i class="fa-solid fa-shield-halved" style="color: #81c0aa;"></i> Permission control**: Maintainers decide what contributions get merged.

> **<i class="fa-solid fa-handshake-angle" style="color: #81c0aa;"></i> Social cue:**
> Contributing to open source is more than just writing code.
> GitHub allows you to collaborate, discuss ideas, and learn from others.

## Why contribute to open source?

Contributing to open source is a way to **build skills, expand your network, and give back** to projects you care about.

- **Improve your skills**: Gain hands-on experience with real-world projects.
- **Grow your network**: Connect with developers, maintainers, and potential collaborators.
- **Showcase your work**: Contributions become part of your **public portfolio**.
- **Support tools you use**: Many contributors improve projects they rely on for work or hobbies.
- **Learn from others**: See how experienced developers write and manage code.

> **<i class="fa-solid fa-handshake" style="color: #81c0aa;"></i> Social cue:**
> Open source is collaborative—every contribution, big or small, helps the community.

## Using GitHub for personal projects

Many people start using GitHub as a **personal version control tool**.
This means tracking changes to your own work **without** collaborating with others.

### Solo workflow

1. **<i class="fa-solid fa-download" style="color: #81c0aa;"></i> Clone a repository**: Copy the project to your local computer.
2. **<i class="fa-solid fa-edit" style="color: #81c0aa;"></i> Work locally**: Edit files and make changes.
3. **<i class="fa-solid fa-save" style="color: #81c0aa;"></i> Commit changes**: Save changes with a description of what was modified.
4. **<i class="fa-solid fa-upload" style="color: #81c0aa;"></i> Push changes**: Upload updates to GitHub as a backup.

:::{figure} /images/github/use-github-yourself.png
:alt: "Visual representation of using GitHub for personal projects."
:::

### Use Git and GitHub collaboratively
> **<i class="fa-solid fa-user" style="color: #81c0aa;"></i> Social cue:**
> GitHub is **useful even when working alone**. It creates a backup of your work and
> allows you to track changes over time—helpful for research, coding, or writing.

In the open source world, GitHub is used to work collaboratively on software. GitHub is a shared platform where contributors can propose changes, review each other's work, and integrate updates through features like pull requests and issue tracking.
## Using GitHub collaboratively

In a collaborative setting, your workflow looks something like this:
GitHub is widely used in **open source** and **team-based projects** where multiple people work on the same codebase.

1. **Fork a Repository**: Create your own copy of the project on GitHub.
2. **Clone Locally**: Download your fork to work on it.
3. **Make and Commit Changes**: Edit files and save your changes locally.
4. **Push to Your Fork**: Upload updates to your GitHub fork.
5. **Open a Pull Request**: Suggest changes to the main project.
6. **Collaborate and Merge**: Review and merge changes into the main project.
### Collaborative workflow

Note that the big change in workflow is that you are forking a main repository rather than working directly on that main repository. And you have a team of people who will review and decide if changes made through pull requests should be merged (or integrated into the existing code base).
1. **<i class="fa-solid fa-code-fork" style="color: #81c0aa;"></i> Fork a repository**: Create your own copy of the project on GitHub.
2. **<i class="fa-solid fa-download" style="color: #81c0aa;"></i> Clone locally**: Download your fork to work on it.
3. **<i class="fa-solid fa-edit" style="color: #81c0aa;"></i> Make and commit changes**: Edit files and save your changes.
4. **<i class="fa-solid fa-upload" style="color: #81c0aa;"></i> Push to your fork**: Upload updates to your GitHub copy.
5. **<i class="fa-solid fa-paper-plane" style="color: #81c0aa;"></i> Open a pull request**: Suggest changes to the main project.
6. **<i class="fa-solid fa-people-arrows" style="color: #81c0aa;"></i> Collaborate and merge**: Review and integrate updates.

:::{figure} /images/github/use-github-collaboratively.png
:alt: Alt here
> **Key difference:** Instead of pushing changes directly to the project, you first **fork it** and work within your own copy before submitting a **pull request** to propose changes.

:::{figure} /images/github/use-github-collaboratively.png
:alt: "Diagram of how GitHub enables collaborative work through forking and pull requests."
:::

## What's next
> **<i class="fa-solid fa-users" style="color: #81c0aa;"></i> Social cue:**
> Working on GitHub is more than writing code—it’s about **communication, teamwork, and reviewing each other's work**.



## Summary

| | **Feature** | **Solo Use** | **Collaborative Use** |
|-|---------------------|--------------------------------|--------------------------------------|
| | **Main goal** | Personal version control | Team-based development |
| | **Repository type** | Single personal repo | Forked repositories linked together |
| | **Workflow steps** | Clone, edit, commit, push | Fork, branch, pull request, merge |
| | **Review process** | Self-review changes | Maintainers review contributions |

:::{admonition} What's next?
:class: seealso
Now that you understand GitHub's role in **open source** and **collaboration**,
you're ready to dive into **contributing to a project!**

*****

<i class="fa-brands fa-github-alt"></i> [Get started with activities to guide you through your first contribution →](your-first-contribution)
<i class="fa-brands fa-github-alt"></i> [Learn how to identify an issue →](identify-issue)
<i class="fa-brands fa-github-alt"></i> [Learn how to fork a repository →](fork-repository)
:::

In this lesson series, you will learn how to work collaboratively using GitHub. The lessons will combine the technical elements you need to use git and GitHub with the social dynamics that are not often taught.

:::{todo}
resources
<https://www.youtube.com/watch?v=eWxxfttcMts>
:::

:::{toctree}
:maxdepth: 2
:hidden:

About These Lessons <self>

:::

:::{toctree}
:caption: Contribute to Another Repo
:maxdepth: 2
Expand All @@ -91,7 +160,7 @@ Clone a GitHub Repo <clone-repo>
:maxdepth: 2
:hidden:

Use GitHub With Friends (vs. by yourself) <self>

What is Git/GitHub <what-is-git-github>
GitHub Social platform <github-social-platform>
Use GitHub codespaces <github-codespaces>
Expand Down
40 changes: 22 additions & 18 deletions github-git/pull-request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,13 @@ Animated gif showing that GitHub will prompt you to make a new pul request when
When you setup your pull request, you will need to specify the head and the base. The head refers to the branch that is a-HEAD of the parent repository--ie a branch on your fork! The base is the parent repository that you wish to submit changes to.
:::

When you create your pull request, take note of the head and base targets.
The repo that you wish to update is the base repo) and the
repo that contains the content that you want to use to update the base
(the head repo).
When creating a **pull request (PR)**, you need to define where your changes should be added and where they come from.

- **<i class="fa-solid fa-database" style="color: #81c0aa;"></i> Base:** The repository where you want your changes to be merged. *(This is usually the original repo you forked.)*
- **<i class="fa-solid fa-code-branch" style="color: #81c0aa;"></i> Head:** The repository containing your changes. *(This is your fork. The copy of the repo that you own, where you made edits.)*


> **🔹 Quick way to remember:** The **head** is "ahead" of the base, meaning it has new changes that the base repository does **not** yet have.

In this example, you want to update:

Expand All @@ -75,17 +78,6 @@ In this example, you want to update:
> go to the right place. If you accidentally select the wrong base, your PR might not
> reach the maintainers you intended. Double-check this before submitting!

The above pull request configuration tells **GitHub** to update the base repository with contents from your forked repository or the head repository.


### Set up a pull request: base vs. head

When creating a **pull request (PR)**, you must define where your changes should be added and where they come from.

- **<i class="fa-solid fa-database" style="color: #81c0aa;"></i> Base:** The repository where you want your changes to be merged. *(This is usually the original repo you forked.)*
- **<i class="fa-solid fa-code-branch" style="color: #81c0aa;"></i> Head:** The repository containing your changes. *(This is your fork. The copy of the repo that you own, where you made edits.)*

> **🔹 Quick way to remember:** The **head** is "ahead" of the base, meaning it has new changes that the base repository does **not** yet have.

:::{todo}

Expand Down Expand Up @@ -135,9 +127,15 @@ title and description, click on “Create Pull Request” one more time to submi
If you go to the parent repository, you will see the PR listed there.

:::{tip}
You can modify the title and description of your pull request at any time - even after you've submitted the pull request.
Take note that your pull request can be modified at any time, but do so with caution.

* You can modify the title and description of your pull request even after you've submitted it.
* New commits to your working branch will be visible in your open PR until they are merged.
*
Any changes made to it will potentially delay a review from maintainers. It's best to submit the PR, review it, and leave it unchanged until you get feedback.
:::


## Close or move a Pull Request to draft

Sometimes, after opening a pull request, you realize it's **not quite ready for review**. In that case, you have two options:
Expand All @@ -157,6 +155,12 @@ When you create a **pull request (PR)**, GitHub directs you to the parent reposi

The repo owner may request modifications before merging. Any future commits to the same branch will be added to the PR until it is merged.

::: {note}
<i class="fa-solid fa-wand-sparkles"></i> New commits to your working branch will continue updating the open PR until it is merged.



:::{admonition} You did it!
:class: seealso

Once you've opened your **pull request (PR)**, you wait for a response from the maintainer team! Congratulations on submitting a contribution to open source!

:::
12 changes: 6 additions & 6 deletions github-git/your-first-contribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ kernelspec:
language: python
name: python3
myst_html_meta:
"title": "Intro to Collaborative GitHub: Make your first contribution to open source"
"description lang=en": "Learn the steps involved with using GitHub to collaborate and contribute to open source code and documentation. A beginner-friendly guide."
"keywords": "GitHub, OpenSource, beginner-friendly"
"property=og:locale": "en_US"
og:image: /images/github/steps-to-contribute.png
og:image:alt: An image that shows the steps for contributing to open source on GitHub.
"title": "Intro to Collaborative GitHub: Make your first contribution to open source"
"description lang=en": "Learn the steps involved with using GitHub to collaborate and contribute to open source code and documentation. A beginner-friendly guide."
"keywords": "GitHub, OpenSource, beginner-friendly"
"property=og:locale": "en_US"
"og:image": /images/github/steps-to-contribute.png
"og:image:alt": An image that shows the steps for contributing to open source on GitHub.
---

# Mastering GitHub Collaboration Skills
Expand Down