From c8e7ff37e3a45f32180f984dc40fbdb4e8d01218 Mon Sep 17 00:00:00 2001 From: Leah Wasser Date: Tue, 21 Jan 2025 18:16:40 -0700 Subject: [PATCH] add: new content to edit file lesson docs: update README.md [skip ci] docs: update .all-contributorsrc [skip ci] add: edit lesson fix: pr page plus screencasts fix: rename and reorg add: metadata to core pages rewrite: social cues added throughout fix: metadata fix: add social elements fix: cleanup and add social context fix: edits from group review fix: new landing page - intro Fix: final edits to lessons fix: links --- .all-contributorsrc | 9 + README.md | 1 + conf.py | 6 +- github-git/4-edit-commit-files.md | 45 ---- github-git/5-pull-request.md | 14 -- github-git/{6-clone-repo.md => clone-repo.md} | 11 +- github-git/edit-commit-files.md | 104 ++++++++++ github-git/{3-fork-repo.md => fork-repo.md} | 26 ++- ...et-to-know-repo.md => get-to-know-repo.md} | 8 +- github-git/github-codespaces.md | 44 ++++ github-git/github-social-platform.md | 101 ++++++++- ...{2-identify-issue.md => identify-issue.md} | 52 +++-- github-git/intro.md | 153 +++++++++----- github-git/pull-request.md | 166 +++++++++++++++ github-git/ways-to-contribute.md | 60 ++++++ github-git/what-is-git-github.md | 12 +- github-git/your-first-contribution.md | 193 ++++++++++++++++++ images/github/contribute-no-fork.gif | Bin 0 -> 3596199 bytes images/github/create-pr-fork.gif | Bin 0 -> 1201737 bytes images/github/edit-commit-file.gif | Bin 0 -> 8023326 bytes images/github/edit-file-github-fork.png | Bin 0 -> 621143 bytes images/github/edit-file-new-branch.gif | Bin 0 -> 3132562 bytes images/github/fork-clone-repo.png | Bin 0 -> 51409 bytes images/github/fork-repo.gif | Bin 0 -> 628448 bytes images/github/git-what-are-commits.png | Bin 0 -> 51198 bytes images/github/github-create-pull-request.png | Bin 0 -> 310713 bytes .../github/github-issues-good-first-issue.png | Bin 0 -> 527228 bytes images/github/github-pr-targets-head-base.png | Bin 0 -> 597673 bytes images/github/pr-check-files.gif | Bin 0 -> 1220796 bytes images/github/use-github-collaboratively.png | Bin 104077 -> 93946 bytes images/github/use-github-yourself.png | Bin 112746 -> 220931 bytes index.md | 2 +- 32 files changed, 839 insertions(+), 168 deletions(-) delete mode 100644 github-git/4-edit-commit-files.md delete mode 100644 github-git/5-pull-request.md rename github-git/{6-clone-repo.md => clone-repo.md} (91%) create mode 100644 github-git/edit-commit-files.md rename github-git/{3-fork-repo.md => fork-repo.md} (95%) rename github-git/{1-get-to-know-repo.md => get-to-know-repo.md} (99%) create mode 100644 github-git/github-codespaces.md rename github-git/{2-identify-issue.md => identify-issue.md} (89%) create mode 100644 github-git/pull-request.md create mode 100644 github-git/ways-to-contribute.md create mode 100644 github-git/your-first-contribution.md create mode 100644 images/github/contribute-no-fork.gif create mode 100644 images/github/create-pr-fork.gif create mode 100644 images/github/edit-commit-file.gif create mode 100644 images/github/edit-file-github-fork.png create mode 100644 images/github/edit-file-new-branch.gif create mode 100644 images/github/fork-clone-repo.png create mode 100644 images/github/fork-repo.gif create mode 100644 images/github/git-what-are-commits.png create mode 100644 images/github/github-create-pull-request.png create mode 100644 images/github/github-issues-good-first-issue.png create mode 100644 images/github/github-pr-targets-head-base.png create mode 100644 images/github/pr-check-files.gif diff --git a/.all-contributorsrc b/.all-contributorsrc index f26dafc..e2d3ae3 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -45,6 +45,15 @@ "code", "review" ] + }, + { + "login": "jsdodge", + "name": "J. Steven Dodge", + "avatar_url": "https://avatars.githubusercontent.com/u/4602669?v=4", + "profile": "https://www.sfu.ca/lux/author/j.-steven-dodge/", + "contributions": [ + "review" + ] } ], "contributorsPerLine": 7, diff --git a/README.md b/README.md index 99688ee..222b44d 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d Jeremy Paige
Jeremy Paige

👀 Carol Willing
Carol Willing

👀 Jonny Saunders
Jonny Saunders

💻 👀 + J. Steven Dodge
J. Steven Dodge

👀 diff --git a/conf.py b/conf.py index db058e0..b3cd5fe 100644 --- a/conf.py +++ b/conf.py @@ -22,7 +22,7 @@ # -- Project information ----------------------------------------------------- -project = "pyOpenSci Python Package Guide" +project = "pyOpenSci Open Source Lessons" copyright = f"{current_year}, {organization_name}" author = "pyOpenSci Community" # Version is needed to avoid "cant describe anything fatal error" @@ -105,11 +105,11 @@ # "text": "Python Packaging", "image_dark": "logo-dark-mode.png", "image_light": "logo-light-mode.png", - "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower", + "alt_text": "pyOpenSci Open Source Lessons. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower", }, # Increase this as lessons are added - # set low to hide links to other pyos sites and allow nav between lessons - "header_links_before_dropdown": 3, + "header_links_before_dropdown": 5, "use_edit_page_button": True, "show_nav_level": 2, "navigation_depth": 3, diff --git a/github-git/4-edit-commit-files.md b/github-git/4-edit-commit-files.md deleted file mode 100644 index d315718..0000000 --- a/github-git/4-edit-commit-files.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -jupytext: - text_representation: - extension: .md - format_name: myst - format_version: 0.13 - jupytext_version: 1.16.4 -kernelspec: - display_name: Python 3 (ipykernel) - language: python - name: python3 ---- - -# Your first edits to a file in your fork - -In this lesson, you will edit a documentation file (or a docstring) using the GitHub interface. You do not need to [clone or make a copy of your repo locally](clone-repo) to do this! This is a great way to make your first contribution to open source without using the command line! - -## Make the changes that you said you would make in the issue opened above - -After you have forked the repo and received the OK to move forward with your pull request: - -* Open the file you want to change in your fork. -* Make the edits that you want to make to the file -* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed: -* -> fix: fixed numerous typos in the filename.py file -> fix: updated the code to align with PEP 8 syntax -> fix: fixed typo in docstring text - -::::{admonition} What is a commit?? - -A **commit** is a feature in the [git version control](what-is-git) that is similar to saving your changes with a note explaining what you did. - - - -:::{figure} /images/github/git-commits-files.png -:alt: Alt here - -::: - -:::: - -:::{todo} -It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too -::: diff --git a/github-git/5-pull-request.md b/github-git/5-pull-request.md deleted file mode 100644 index 4c01083..0000000 --- a/github-git/5-pull-request.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -jupytext: - text_representation: - extension: .md - format_name: myst - format_version: 0.13 - jupytext_version: 1.16.4 -kernelspec: - display_name: Python 3 (ipykernel) - language: python - name: python3 ---- - -# Submit a Pull Request diff --git a/github-git/6-clone-repo.md b/github-git/clone-repo.md similarity index 91% rename from github-git/6-clone-repo.md rename to github-git/clone-repo.md index 29325be..c0e016e 100644 --- a/github-git/6-clone-repo.md +++ b/github-git/clone-repo.md @@ -9,9 +9,14 @@ kernelspec: display_name: Python 3 (ipykernel) language: python name: python3 +myst_html_meta: + "title": "How to Clone a GitHub Repository to Work Locally: Collaborative GitHub for beginners" + "description lang=en": "Learn how to clone or make a copy of a GitHub repository online on your computer so you can work locally." + "keywords": "GitHub, OpenSource" + "property=og:locale": "en_US" --- -(clone-repo)= +(clone-repository)= # Clone a GitHub Repository to Work Locally How to clone a repo. @@ -38,13 +43,13 @@ On the main **GitHub.com** page of the repository, you can click on the green bu `https://github.com/your-username/repo-name` - +::::{todo} :::{figure} /images/github/image-coming-soon.png :alt: alt text here You can make a local copy of your forked repository on your computer with the git clone command. ::: - +:::: :::{tip} You can copy the URL directly from your web browser, or in some cases, you might already know the URL. However, in many cases, you will come across a new **GitHub.com** repository on your own and will need to follow these instructions to copy the URL for future use. diff --git a/github-git/edit-commit-files.md b/github-git/edit-commit-files.md new file mode 100644 index 0000000..0f8ea14 --- /dev/null +++ b/github-git/edit-commit-files.md @@ -0,0 +1,104 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +myst_html_meta: + "title": "How to edit and commit changes to a file on GitHub: Intro to Collaborative GitHub" + "description lang=en": "Learn how to edit a file and then commit changes to that file to version control. All in the GitHub interface." + "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. +--- + +# Your First Edits to a File in Your Fork: Edit & Commit + +Now that you've [identified and comment on an issue](identify-issue), [forked the repository](fork-repo) and received approval to work on an issue, it's time to make your changes. + +> **💡 Reminder:** Your fix should be **small and text-based**, like updating documentation or fixing a typo. + +:::{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. + +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). + +::: + +## How to edit a file in your fork + +GitHub lets you edit files right in your browser. Here’s how: + +1. Navigate to **your fork** of the repository. +2. Find the file you want to edit. +3. Click the Edit button. +4. Make your changes and **commit** them. + +:::{figure} /images/github/edit-commit-file.gif +:alt: "GIF showing how to edit and commit a file on GitHub." + +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. + + +## 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](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** | Quick edits (typos, small fixes) | No setup needed, edit in browser | Can only commit one file at a time | +| | **GitHub Codespaces** | 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? + +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. + +::: + +### How commits work + +:::{figure} /images/github/git-commits-files.png +:alt: A visual example demonstrating how Git tracks changes to a document through commits. The image shows an “Original File” with its initial text, followed by two commits. The first commit adds a new paragraph of text, with the changes highlighted in green and the commit message, “Fix: added a new paragraph to clarify text.” The second commit fixes typos in the text, with the edits highlighted in green and the commit message, “Fix: copy edits.” At the bottom, a comparison shows the document after each commit, illustrating how the file evolves with changes. + +Each commit represents **a set of changes** at a specific time. +::: + +> **🛠 Do you need to undo changes that you made?** Git lets you revert to an earlier commit, so you don’t have to worry about breaking anything. + + +:::{figure} /images/github/git-what-are-commits.png +:alt: A diagram explaining Git commits and their role in version control. The top section shows a timeline of circular commits, each paired with a file icon to represent file changes, with the text: “Each commit represents one or more file changes made at a specific point in time.” The middle section highlights the “Latest Commit” on the timeline, showing it as the current state of the repository. The bottom section demonstrates the concept of reverting, with an arrow pointing from a later commit back to a previous one, illustrating that Git allows reverting or going back to earlier commits. The text reads: “You can also always revert or return to a previous commit. This is what makes Git powerful.” + +You can always **undo or revert** changes using Git. +::: + +:::{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. + +***** + +[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 from the community that we could share some stories about. +::: diff --git a/github-git/3-fork-repo.md b/github-git/fork-repo.md similarity index 95% rename from github-git/3-fork-repo.md rename to github-git/fork-repo.md index a9e86ce..2a356d0 100644 --- a/github-git/3-fork-repo.md +++ b/github-git/fork-repo.md @@ -24,8 +24,8 @@ myst_html_meta: --- (fork-repository)= -# A Guide to Forks on GitHub Forks +# A Guide to Forks on GitHub Forks :::{admonition} What You Will Learn :class: tip @@ -39,7 +39,7 @@ Forking a repository **creates a copy** in your GitHub account while keeping a l - **Edit without concern**: Work on your fork without affecting the original project. - **Stay up to date**: Sync your fork with the latest changes from the original repo. -- **Propose changes**: Suggest edits by submitting a **pull request** to the original repository. +- **Propose changes**: Suggest edits by submitting a **pull request** to the original repository. > ** Example**: You want to fix a typo in a project’s documentation. Instead of requesting permission, you fork the repo, make the fix, and submit a pull request with your update. @@ -64,20 +64,17 @@ The URL of your fork will be: `https://github.com/your-username/pyos-demo-package-contribute` - :::{tip} -The number next to the button tells you how many times other users have forked the repository. +The number next to the button tells you how many times other users have forked the repository. ::: - :::{figure} /images/github/fork-repo-animated.gif -:alt: GIF showing how to fork a repository on GitHub +:alt: GIF showing how to fork a repository on GitHub To fork a repo, navigate to it on GitHub and click the **Fork** button. Your copy will appear under your account. ::: - -:::{admonition} Who owns the repo? +:::{admonition} Who owns the repo? Every GitHub repository has an **owner**, which can be: @@ -87,8 +84,9 @@ Every GitHub repository has an **owner**, which can be: The **owner’s username appears first in the URL**, showing who controls the repository. **Example**: - - A personal repo: `https://github.com/your-gh-username/my-project` - - An organization-owned repo: `https://github.com/pyOpenSci/repo-name` + +- A personal repo: `https://github.com/your-gh-username/my-project` +- An organization-owned repo: `https://github.com/pyOpenSci/repo-name` If you **fork a repo**, your GitHub username becomes the owner of the fork: @@ -96,7 +94,6 @@ If you **fork a repo**, your GitHub username becomes the owner of the fork: ::: - ## What happens after you fork a repo? Your fork **is a separate copy**, but it remains linked to the original repository. @@ -105,27 +102,28 @@ Your fork **is a separate copy**, but it remains linked to the original reposito - **The original repo stays at:** `https://github.com/original-owner/repository-name` > ** You can now:** +> > - Make changes without affecting the original repository. > - Keep your fork updated as the original repo evolves. > - Submit changes back using a **pull request**. - + ::::{todo} /images/github/fork-structure.png :alt: "Diagram showing how forking creates a personal copy linked to the original." Graphic: A simple diagram showing "Original Repo → Fork → Your Account". :::: - ## Keep your fork in sync Your fork doesn't automatically get updated when the **original repository is updated**. Periodically, you will need to **sync your fork** to keep it current. To sync a GitHub fork: + 1. **Go to your fork** on GitHub. 2. **Click the** **Sync fork** **button** (available on GitHub’s UI). 3. Your fork's main branch will now match the latest version of the original repository. This means that it has the most recent commits that have been made to the parent repository. -:::{todo} +:::{todo} /images/github/sync-fork.png :alt: "GitHub interface showing how to sync a fork with the original repo." Graphi: Screenshot of GitHub’s "Sync Fork" button diff --git a/github-git/1-get-to-know-repo.md b/github-git/get-to-know-repo.md similarity index 99% rename from github-git/1-get-to-know-repo.md rename to github-git/get-to-know-repo.md index 965c29e..7d645a0 100644 --- a/github-git/1-get-to-know-repo.md +++ b/github-git/get-to-know-repo.md @@ -31,6 +31,7 @@ Before contributing, it's important to **familiarize yourself with the repositor ### 1. Check the README and CONTRIBUTING guide The **README** provides an overview of the project, its purpose, and how it is used. Often, it also links to the project's contributing and development guides. + - **Review the README file**: The [**README.md** file](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/README.md) will help you understand the project's goals. - **Read the CONTRIBUTING guide**: The [**CONTRIBUTING.md** file](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/CONTRIBUTING.md) explains what types of contributions are accepted and the expected workflow. @@ -43,6 +44,7 @@ Above is a screenshot of the pyOpenSci practice repo that you will use. Notice t ::: (labels-responsive)= + ### 2. Look at project activity and maintainer responsiveness - Scan the **issues and pull requests** sections on GitHub to see how long it generally takes for maintainers to respond. @@ -54,17 +56,19 @@ Above is a screenshot of the pyOpenSci practice repo that you will use. Notice t ### 3. Understand the project’s infrastructure Some repositories have specific **code and text format and workflow requirements**. Make sure to check if the project uses: + - **Code formatters and linters**: Does the project use [code formatters or linters](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#python-package-code-style-format-and-linters)? - **Continuous Integration (CI)**: Are there automated tests and checks that run when a new PR is submitted? - **Licensing**: The [project’s license](https://www.pyopensci.org/python-package-guide/documentation/repository-files/license-files.html) dictates how you can use, modify, and distribute the code. - The **MIT and BSD-3 licenses** permit broad use with attribution; these licenses are common in the scientific open source ecosystem. - - A **GPL license** requires derivative works to follow the same open source terms. This is what's known as a [copy-left license](https://www.pyopensci.org/python-package-guide/documentation/repository-files/license-files.html#use-open-permissive-licenses-when-possible). + - A **GPL license** requires derivative works to follow the same open source terms. This is what's known as a [copy-left license](https://www.pyopensci.org/python-package-guide/documentation/repository-files/license-files.html#use-open-permissive-licenses-when-possible). > ** Social cue:** If the project follows **consistent coding standards and has CI in place**, it likely has an **organized review process**, that is setup to accept contributions. Further, if the project uses tools such as the [pre-commit ci bot](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#pre-commit-ci), code formatting and linting might be possible on GitHub within the pull request it self using CI. This means you won't need to setup a development environment to "clean up" any changes that you make in a PR. ### 4. Check for a Code of Conduct A **Code of Conduct** helps ensure a **welcoming and respectful** community. + - If one exists, read it to understand community expectations. - If missing, check discussions in issues and pull requests to gauge how maintainers interact with contributors. @@ -81,6 +85,6 @@ A **Code of Conduct** helps ensure a **welcoming and respectful** community. The above steps will help you determine whether a project is **welcoming, responsive, and well-maintained**, making it a great place to contribute! 🚀 - ## Next steps + Once you have explored and gotten to know the repository and decided that it's a good project to contribute to, it's time to [find an issue to work](identify-issue). You will learn more about that next. diff --git a/github-git/github-codespaces.md b/github-git/github-codespaces.md new file mode 100644 index 0000000..6a2b68c --- /dev/null +++ b/github-git/github-codespaces.md @@ -0,0 +1,44 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +--- + +# Code spaces and contributing to open source + +[In the edit commit files lesson](edit-commit-files), you learned how to directly change a file on GitHub in the browser. You didn't need a special development environment to make that change in this lesson. + +However, in some cases, developers have set up a codespace for you to use on GitHub. A codespace is a cloud-based development environment that has been set up for you (or that you can create yourself) with all of the tool and dependencies that you need to work on a project. + +Codespaces are a feature that is specific to GitHub and are free for up to 60 hours a month. After that 60 hours, you need to pay for the service. + +(about-codespace)= +## What is a codespace + +GitHub Codespaces is a cloud-based development environment integrated into GitHub. It provides fully configured, container-based environments that you can use to modify files in a GitHub repository. +Codespaces are customizable, allowing users to define their environment using .devcontainer configuration files. The codespaces we set up for the Fall Festival run Visual Studio Code. This will allow you to work on activities during the workshop in the cloud fully. You can learn more about GitHub Codespaces here. + +:::{important} +Important: codespaces are free to run for up to 60 hours a month. Thus, it is important that you shut down your CodeSpace each day after the workshop ends to ensure that you don’t run out of credits. +::: + +## View & manage open codespaces + + + +How to open a codespace +Codespaces are associated with each GitHub user’s account (they are not associated with pyOpenSci / our GitHub organization. If you see the screenshot below, you haven’t launched a codespace from this repository before. In this case, click on Create Codespace on main. This will create a codespace for you using the configuration file provided in the main branch of our organization. + +You might see the image below if you have never used a codespace before. That is fine - click on the green button that says: Create codespace on main. + +:::{todo} +from our fall festival content + +::: diff --git a/github-git/github-social-platform.md b/github-git/github-social-platform.md index a221844..76f0260 100644 --- a/github-git/github-social-platform.md +++ b/github-git/github-social-platform.md @@ -13,10 +13,9 @@ kernelspec: # Community Interaction Best Practices on GitHub -🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧 ## Introduction -GitHub is more than just a platform for hosting code—it’s a **social platform** where developers, researchers, and contributors work together to create, improve, and share projects. Behind every username is a person who deserves respect and appreciation. +GitHub is more than just a platform for hosting code—it’s a **social platform** where developers, researchers, and contributors work together to create, improve, and share projects. Behind every username is a person who deserves respect and appreciation. This lesson will teach you how to interact constructively and positively within the GitHub community. Whether submitting an issue, reviewing someone else’s work, or asking for help, following these best practices will help you collaborate effectively and maintain a welcoming environment. @@ -25,16 +24,19 @@ This lesson will teach you how to interact constructively and positively within Effective communication on GitHub ensures a productive and respectful collaboration environment. Whether you're raising an issue, reviewing code, or contributing to a discussion, these principles will help you interact constructively. ### Respect and professionalism + - Treat everyone with respect, even when disagreements arise. - Remember that many maintainers and contributors volunteer their time and expertise to the community. - Use polite and appreciative language when reaching out or giving feedback. _Example: "Thank you for creating this tool. It's been really helpful!"_ ### Patience + - Be understanding if responses to issues or pull requests take time. - Open-source maintainers often juggle multiple responsibilities outside their projects. ### Clarity and thoughtfulness + - **Use clear and concise language**: - Clearly describe issues, bugs, or suggestions to avoid confusion. - Avoid unnecessary jargon or overcomplicating explanations. @@ -46,19 +48,19 @@ Effective communication on GitHub ensures a productive and respectful collaborat - Use **reactions** (like 👍 or ❤️) to express agreement or appreciation without cluttering threads with “+1” comments. ### Constructive feedback + - Avoid harsh language, blame, or criticism. - Frame suggestions as questions or alternatives: _"What if we try this approach?"_ instead of _"This is wrong."_ - Acknowledge positive aspects alongside suggestions for improvement. :::{todo} -Move this to the pr page once I create it. +Move this to the pr page once I create it. ## 3. When Contributing to a Repository - - ### Opening Pull Requests + - **Describe the Change**: Clearly explain what you’re proposing and why it’s needed. - **Follow Contribution Guidelines**: Adhere to any style or workflow rules outlined in the repository. - **Be Open to Feedback**: Expect to receive suggestions for improvement and revise your pull request accordingly. @@ -66,3 +68,92 @@ Move this to the pr page once I create it. Example Pull Request Description: ::: + +## 🔍 Social Cues for Contributing to Open Source + +When contributing to an open-source project, it’s not just about **fixing code**— +it’s also about **collaborating effectively with maintainers and the community**. +Here are key social cues to follow: + +### 1️⃣ Help Maintainers Keep Track of Who’s Working on What + + **Open an issue first before submitting a PR.** + +- This prevents duplicate work and ensures the maintainers **know who is working on what**. +- If an issue already exists, **comment on it** instead of creating a new one. + + **Avoid surprising maintainers with a PR.** + +- Some projects may not be ready for the change you're suggesting. +- Opening an issue first allows maintainers to **provide guidance before you start coding**. + +--- + +### 2️⃣ Respect the Project’s Process + + **Follow issue templates and contribution guidelines.** + +- Many projects have structured templates—**use them** to provide all necessary details. +- If guidelines exist, reference them in your issue to show you're **aligning with their workflow**. + + **Ask before making major changes.** + +- If your fix changes functionality, check with maintainers before proceeding. +- A simple “Would this be useful?” can save **time for both you and the maintainers**. + +--- + +### 3️⃣ Acknowledge the Maintainers’ Time & Role + + **Maintain respectful communication.** + +- Many maintainers **volunteer their time**—make your requests **clear and easy to understand**. +- If you're waiting on a response, be patient, and after a reasonable time, you can **politely follow up**. + + **Tag maintainers (when appropriate).** + +- If you know who maintains the repo, consider **@mentioning them** in your issue to establish a connection. +- Example: `@maintainer-name, I’d love to help fix this! Any guidance before I start?` + +--- + +### 4️⃣ Communicate Like You Would in Real Life + + **Be polite and professional.** + +- Open source is about **collaborating with people you’ve never met**. +- Treat maintainers **as you would a colleague**—respectful and appreciative of their time. + + **Introduce yourself in your first issue comment.** + +- If you’re new, a friendly introduction can make it easier to build relationships. +- Example: + > “Hey everyone! 👋 I’m new to contributing here and would love to help with this issue. Let me know if there’s anything I should consider before getting started!” + +--- + +### 5️⃣ Build Trust Through Small Contributions + + **Start small to establish credibility.** + +- First contributions aren’t just about code—they're about **building trust with the community**. +- **Small fixes** (like documentation updates or typo corrections) are a great way to get started. + + **Contributions add up over time.** + +- Even small changes **help the project grow** and demonstrate your commitment. +- Once maintainers recognize your contributions, they’re more likely to engage with your work. + +--- + +### **✨ Summary: Contribute Thoughtfully & Respectfully** + +✅ Open issues before submitting PRs to **help maintainers stay organized**. +✅ Follow contribution guidelines to **respect the project’s workflow**. +✅ Communicate professionally to **build relationships in the open-source community**. +✅ Start with **small, impactful contributions** to establish trust. + +--- + +🚀 **By keeping these social cues in mind, you’ll not only contribute code but also +become a valued member of the open-source community!** diff --git a/github-git/2-identify-issue.md b/github-git/identify-issue.md similarity index 89% rename from github-git/2-identify-issue.md rename to github-git/identify-issue.md index 4c770e2..a959bdb 100644 --- a/github-git/2-identify-issue.md +++ b/github-git/identify-issue.md @@ -24,7 +24,7 @@ myst_html_meta: Contributing to an open source project starts with identifying an issue to work on. Open issues help developers track bugs, new features, or needed improvements in a repository. Whether you have a specific fix in mind or are looking for ideas, exploring existing issues is the best place to start. -As discussed in the [get to know a repo lesson](labels-responsive), the way issues are labeled and organized can both help you find issues that maintainers want help with and also tell you a lot about a project. If you see +As discussed in the [get to know a repo lesson](labels-responsive), the way issues are labeled and organized can both help you find issues that maintainers want help with and also tell you a lot about a project. If you see beginner-friendly labels like **"good first issue"** or **"help wanted,"** it's a clear signal that the maintainers welcome new contributors. Further those might be good issues for you to start working on! :::{figure} /images/github/github-issues-good-first-issue.png @@ -35,16 +35,16 @@ pyOpenSci runs beginner-friendly sprints and spends time curating issues for new contributors to work on during these events. ::: -This lesson guides you through **finding or creating an issue** in a repository you don’t own. +This lesson guides you through **finding or creating an issue** in a repository you don’t own. -## How to find an issue to work on +## How to find an issue to work on Generally, when you start contributing, there are two pathways: 1) you already have an issue in mind that you want to work on, or 2) you don't know what you want to work on yet; you'd like to see what the project needs first. Regardless of the pathway that you take, you'll want to remember two things: 1. You always want to search for existing issues before opening a new one 2. You want to link the work you do in a pull request back to the issue you worked on. -Both steps above make it easier for maintainers to keep their list of issues organized and to close issues as they are addressed. +Both steps above make it easier for maintainers to keep their list of issues organized and to close issues as they are addressed. > ** Social cue:** > Regardless of your pathway, you'll spend some time searching through issues. You want to demonstrate your willingness to put in effort before raising an issue. @@ -64,8 +64,7 @@ Your comment might look like this: - **If it doesn’t exist**, you can [create a new one](create-issue) (*see below*). - -### Tips for effectively searching through GitHub issues +### Tips for effectively searching through GitHub issues Before opening a **new** issue, check whether the problem has already been raised by searching through both **open** and **closed** issues. When searching, consider the following: @@ -74,23 +73,21 @@ Before opening a **new** issue, check whether the problem has already been raise So be sure to scan both open and closed issues returned in a search. - ** Search using symbols or variable names**: Searching for specific variable names or function signatures can help find related discussions if the issue is related to code. - > ** Social Cue:** Opening an issue (or commenting on an existing one) helps maintainers track who is working on what and prevents duplicate work. It also ensures the issue can be properly closed once your pull request is merged. A PR without an issue might catch maintainers off guard, so confirming before starting makes collaboration smoother. - -### 2. You're looking for an issue to work on +### 2. You're looking for an issue to work on If you don’t have a specific issue in mind, explore the **open issues** list to find something that interests you. A great place to start is by looking for labels like **"good first issue"** or **"help wanted"**—these are beginner-friendly and often well-scoped. - **Start small**—fixing typos, improving documentation, or tackling minor bugs are great first contributions. The better scoped your issue is, the easier it will be for you to complete the work and get it merged. - **Leave a comment** on the issue to let maintainers know you'd like to help. - -> ** Social cue:** Leaving comments in a new repository can feel intimidating, but most -maintainers appreciate respectful communication and enthusiasm. If a project -isn’t open to contributions, they will let you know—and there are plenty of + +> ** Social cue:** Leaving comments in a new repository can feel intimidating, but most +maintainers appreciate respectful communication and enthusiasm. If a project +isn’t open to contributions, they will let you know—and there are plenty of other projects to explore! -### How to know if an issue is available to work on +### How to know if an issue is available to work on Even if you find an open issue that interests you, it’s important to check if someone is already working on it. @@ -105,8 +102,8 @@ Even if you find an open issue that interests you, it’s important to check if > Just because someone expressed interest in an issue doesn’t always mean they are actively working on it. > If the last comment is old, the contributor may have moved on. Asking politely shows respect for their effort. - (create-issue)= + ## How to create a new issue If an issue doesn’t already exist for the thing you'd like to work on, here’s how to create a new one: @@ -116,7 +113,7 @@ If an issue doesn’t already exist for the thing you'd like to work on, here’ :::{tip} Some projects use templates for reporting **bugs, documentation fixes, or new features**. If a template is available, fill it out—it helps maintainers quickly understand your issue. -::: +::: 3. Create a **clear title** summarizing what you’d like to fix. @@ -131,11 +128,12 @@ Some projects use templates for reporting **bugs, documentation fixes, or new fe ::: 4. Be **specific about what you'd like to fix**: - * Ideally, the issue that you want to address focuses on one thing and isn't too broad. - * Explain the problem or fix you’re proposing. - * For **code bugs**: include steps to reproduce the issue; also describe what you expected would happen, and what actually happened when you ran the code. - * For **documentation**: link to the page and describe what you’d like to update or enhance. - * For **new features**: describe what will happen once it is implemented + +- Ideally, the issue that you want to address focuses on one thing and isn't too broad. +- Explain the problem or fix you’re proposing. +- For **code bugs**: include steps to reproduce the issue; also describe what you expected would happen, and what actually happened when you ran the code. +- For **documentation**: link to the page and describe what you’d like to update or enhance. +- For **new features**: describe what will happen once it is implemented :::{figure} /images/github/open-issue.gif :alt: alt text here @@ -148,14 +146,14 @@ Some projects use templates for reporting **bugs, documentation fixes, or new fe Maintainers are often volunteers, so the more information you provide, the easier it is for them to support you. A well-crafted issue saves time and helps get faster responses. >** Social Cue:** Before submitting the issue, ask yourself: -> * Could someone unfamiliar with the project understand this issue? -> * Did I provide enough detail for a maintainer to respond without extra questions? +> +> - Could someone unfamiliar with the project understand this issue? +> - Did I provide enough detail for a maintainer to respond without extra questions? ::: > ** Social Cue:** For smaller projects, tagging a maintainer can help get feedback faster. However, check contributor guidelines first to see if this is encouraged. Example: > `@maintainer-name, I'd love to help with this! Let me know if there's anything I should consider before starting.` - :::{todo} Add section on issue templates, how they work, what they are ::: @@ -178,6 +176,6 @@ Focus on making small, meaningful contributions. Most first contributions are sm If the maintainers invite you to submit a pull request, it's time to: -* [Fork the repository](fork-repository) if you haven't already. -* [Make your changes on a new branch in your fork.](edit-commit-files) -* [Submit a pull request](pull-request) with your updates. +- [Fork the repository](fork-repository) if you haven't already. +- [Make your changes on a new branch in your fork.](edit-commit-files) +- [Submit a pull request](pull-request) with your updates. diff --git a/github-git/intro.md b/github-git/intro.md index e621831..9d9cfd3 100644 --- a/github-git/intro.md +++ b/github-git/intro.md @@ -9,95 +9,150 @@ 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. -🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧 +> This guide covers: +> What GitHub is and how it supports **open source communities** +> How GitHub is used for **both solo work and collaborative projects** +> The difference between **personal vs. team workflows** -GitHub is a social coding platform. -GitHub can be used in two primary ways: **independently** or **collaboratively**. +## GitHub and open source -## Use GitHub by yourself +**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. -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. +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. -If you are using GitHub on your own, your workflow probably looks something like this: +### Why open source communities use GitHub -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. +- ** Global collaboration**: Developers from around the world can contribute. +- ** Version control**: Track every change made to the project. +- ** Transparent discussions**: Use issues and pull requests to propose and review changes. +- ** Permission control**: Maintainers decide what contributions get merged. -:::{figure} /images/github/use-github-yourself.png -:alt: Alt here +> ** 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. + +> ** 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. ** Clone a repository**: Copy the project to your local computer. +2. ** Work locally**: Edit files and make changes. +3. ** Commit changes**: Save changes with a description of what was modified. +4. ** 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 +> ** 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. ** 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. +4. ** Push to your fork**: Upload updates to your GitHub copy. +5. ** Open a pull request**: Suggest changes to the main project. +6. ** 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." ::: +> ** Social cue:** +> Working on GitHub is more than writing code—it’s about **communication, teamwork, and reviewing each other's work**. + + + +## Summary -## What's next +| | **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!** + +***** + + [Get started with activities to guide you through your first contribution →](your-first-contribution) + [Learn how to identify an issue →](identify-issue) + [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} -:caption: Contribute to Another Repo :maxdepth: 2 :hidden: -0. Your contributing path <0-first-contribution> -1. Get to know the repo <1-get-to-know-repo> -2. Find an issue <2-identify-issue> -3. Fork GitHub Repo <3-fork-repo> -4. Edit & commit files <4-edit-commit-files> -5. Submit Pull Request <5-pull-request> +About These Lessons -::: +::: :::{toctree} -:caption: Work locally +:caption: Contribute to Another Repo +:maxdepth: 2 :hidden: -Clone a GitHub Repo <6-clone-repo> +0. Your contributing path +1. Get to know the repo +2. Find an issue +3. Fork GitHub Repo +4. Edit & commit files +5. Submit Pull Request + ::: :::{toctree} -:caption: How To -:maxdepth: 2 +:caption: Work locally :hidden: - -Navigate the Social Dynamics of GitHub - +Clone a GitHub Repo ::: :::{toctree} @@ -105,7 +160,9 @@ Navigate the Social Dynamics of GitHub :maxdepth: 2 :hidden: -Use GitHub With Friends (vs. by yourself) + What is Git/GitHub GitHub Social platform +Use GitHub codespaces +Ways to contribute ::: diff --git a/github-git/pull-request.md b/github-git/pull-request.md new file mode 100644 index 0000000..bd81000 --- /dev/null +++ b/github-git/pull-request.md @@ -0,0 +1,166 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +myst_html_meta: + "title": "How to submit a GitHub pull request: Collaborative GitHub for beginners" + "description lang=en": "Learn how to submit a pull request after making changes to a file in a GitHub repository" + "keywords": "GitHub, OpenSource" + "property=og:locale": "en_US" +--- + +# About Pull Requests + +In the last lesson, you learned how to [make and commit a change to a document in a GitHub repository](edit-commit-files). +In this lesson, you will learn how to submit a pull request after making changes to a file in a GitHub repository. + +A GitHub pull request (**PR**): + +1. **Allows you to suggest changes rather than making them directly to a repo you don't own** in a transparent way. You can't break things by submitting a PR! +1. **Supports Review**: A pull request also triggers a review process where other repository owners and users can review and comment on your changes and suggest edits to your changes line-by-line. This makes incorporateing your changes fully transparent. +1. **Maintainers to manage contributions**: PRs allow maintainers to document, approve, and merge contributions into the project in a consistent way. + +> ** Social cue:** +> A pull request is a **collaborative tool**—it lets maintainers review changes +> before merging them. PRs **show transparency** and let others give feedback, +> making sure every update aligns with the project's goals. + +Pull requests empower you to contribute to the work of others in an open and accessible way, even if you don't have direct access to the repository. + +## How to Submit a GitHub Pull Request + +### Step 1: Open your GitHub pull request + +To start a new pull request,click the `New pull request` button on the main page of your forked repository. Or, if you recently made a change to a branch in your fork, then GitHub will recognize is and prompt you to submit a PR (see the image below). + +:::{figure} /images/github/github-create-pull-request.png +To create a pull request, go to the Pull Request tab in your account. Then click on the New pull request button. +::: + +:::{tip} +You will notice the Pull Request button in different places in the GitHub interface. Note that even tho you see the button on different pages, it does the same thing. +::: + +:::{figure} /images/github/create-pr-fork.gif + +Animated gif showing that GitHub will prompt you to make a new pul request when it notices new commits to a branch in your fork. +::: + +### Step 2: Setup your pull request targets (head and base) + +:::{figure} /images/github/github-pr-targets-head-base.png +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 creating a **pull request (PR)**, you need to define where your changes should be added and where they come from. + +- ** Base:** The repository where you want your changes to be merged. *(This is usually the original repo you forked.)* +- ** 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: + +* **base**: `pyopensci/pyos-demo-package-contribute` with +* **head**: commits in your fork `your-username/pyos-demo-package-contribute`. + + +> ** Social Tip:** +> Choosing the correct **head** and **base** repositories ensures that your changes +> 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! + + +:::{todo} + +/images/github/base-vs-head.png +:alt: "Diagram showing how base and head work in GitHub pull requests." +Create Graphic: Simple diagram with arrows from "Your Fork (Head)" → "Original Repo (Base)" + +::: + +### Step 3: Review your own pull request first + +When comparing repositories in a **pull request (PR)**, GitHub provides a **diff view** of changes between files (diff as in difference). Before submitting the pr, carefully review these changes to ensure that what you intended to submit is in the PR (and nothing else). + +Since others will review your PR, take time to **clean up unnecessary changes** before submitting. Your time upfront will lead to the PR being merged sooner and will make it easier for others to review. + +> ** Social cue:** +> A PR isn't just about submitting changes—it’s about **communicating clearly** with +> maintainers. A well-reviewed PR with **only relevant changes** is easier to merge. +> **Check that your PR doesn’t include unintended file modifications.** + +Before you submit your PR, check: + +1. **The number of files:** Do they match what you intended to modify? +2. **Review changes in each file:** Are all modifications correct and expected? + +:::{figure} /images/github/pr-check-files.gif + +When you first create a PR, be sure to check the PR contents. Notice that the number of files and commits are displayed in this image. Make sure these numbers make sense based upon the changes that you made. +::: + +:::{admonition} Exploring commits +You can also click on the commit titles to see the specific changes in each commit. This is another way to check that the contents of a PR are what you expect them to be. +::: + +### Step 4: Finalize and submit your PR + +Once you've reviewed your PR and everything looks good, it's time to submit it. + +Add a descriptive title and write a brief description of your changes. Pull request titles should be concise and descriptive of the content in the pull request. When you have added your +title and description, click on “Create Pull Request” one more time to submit the PR. + +> ** Social cue:** +> A **clear, descriptive PR title** helps maintainers quickly understand your changes. +> A good title is specific: **"Fix typo in README"** is better than **"Updated file"**. +> Your description should also **explain why** the change was made. + +If you go to the parent repository, you will see the PR listed there. + +:::{tip} +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: + +1. ** Convert it to a draft** – A draft pull request signals to maintainers that your PR is **still in progress** and not yet ready for review. +2. ** Close the PR** – You can close a PR anytime via the **Close pull request** button and reopen it later when you're ready to submit. + +## Who can merge a pull request? + +When you create a **pull request (PR)**, GitHub directs you to the parent repository (e.g., the pyOpenSci repo). At the bottom of the PR, a **Merge Pull Request** button appears, which only the **repository owner** or collaborators can use after reviewing your changes. + +> ** Social cue:** +> Only maintainers can merge PRs, but **you can make their job easier**! +> - **Be responsive** if they ask for changes. +> - **Follow repository guidelines** for PR structure. +> - **Check for review comments** and update your PR accordingly. + +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. + + + + +:::{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! + +::: diff --git a/github-git/ways-to-contribute.md b/github-git/ways-to-contribute.md new file mode 100644 index 0000000..feeee6a --- /dev/null +++ b/github-git/ways-to-contribute.md @@ -0,0 +1,60 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +--- + +```{raw-cell} + +--- +title: TITLE +description: A long time ago +--- +``` + + + + + +# Ways to contribute + +There are several ways to contribute to open source if you are just getting started. This page overviews them and then links to more information about the various steps. + +## Start here if you haven't yet forked the repository + +If you don't already have a fork of the repo that you wish to contribute to in your GitHub account, and you have already opened an issue for the item that you want to fix, you can start by going to GitHub, clicking on the edit button of the file that you want to edit, in the repository that you want to work on (in this case pyopensci/pyos-package-contribute). Do the following: + +If you haven't already forked the repository, then GitHub will do the following: + +1. Go to [https://github.com/pyOpenSci/pyos-demo-package-contribute](https://github.com/pyOpenSci/pyos-demo-package-contribute) +2. Navigate to the file that you wish to edit. Click on the edit button. +3. Given that you haven't forked the repo yet, GitHub will inform you that you need to create a fork first. +4. Once your fork has been created, you can edit the file in the GitHub interface. Note that you are working on your fork of the repo, not the copy that pyOpenSci owns +1. Once you are happy with the changes, you can commit them to version control. In this case you will click on the "propose changes button" to commit your changes. +7. Once you have committed the file (or hit the proposed changes button), GitHub will open a pull request for you in the parent repository. + +:::{figure} /images/github/contribute-no-fork.gif +The GitHub contribute workflow for someone who hasn't yet created a fork of the repo that they wish to contribute to. +::: + +::::{tip} + +If you already have a fork of the repo, when you click on the edit file in the pyOpenSci repo, it will tell you that you will edit the file in your fork. Be careful with this approach, however, because GitHub defaults to editing the file on your main branch. + +:::{figure} /images/github/edit-file-github-fork.png +Don't do this! +::: + +If you already have a fork, we suggest that you edit the file directly from your fork + +:::{figure} /images/github/edit-file-github-fork.png +Edit from your fork directly instead so you can make a new branch. +::: +:::: diff --git a/github-git/what-is-git-github.md b/github-git/what-is-git-github.md index b748a7f..97abf7e 100644 --- a/github-git/what-is-git-github.md +++ b/github-git/what-is-git-github.md @@ -13,8 +13,6 @@ kernelspec: # An overview of Git & GitHub -🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧 - Version control is essential in open source software development and increasingly important in sharing and working on open science workflows. GitHub is the most commonly used cloud-based version control platform. GitHub integrates the power of Git with online collaboration and project management tools. Many think about GitHub as a social coding platform. @@ -45,33 +43,35 @@ Git is a powerful **version control system** that enables teams to track, manage - **Track Changes** Git keeps a detailed history of all changes made to your files. This is critical for open science and open source, as it provides a transparent record of how data, code, or documents have evolved over time. - +::::{todo} :::{figure} /images/github/image-coming-soon.png :alt: Alt here The graphic here shows the commit history: commit 1, commit 2, commit 3, and review merge into main. ::: +:::: - **Branching and Merging** Branches allow users to work independently on new features, experiments, or ideas without affecting the main project. This is particularly useful in research for testing hypotheses or in software development for building new features. Once work is complete, branches can be merged back into the main project. - +::::{todo} :::{figure} /images/github/image-coming-soon.png :alt: Alt here Graphic here showing commit branching ::: +:::: - **Distributed Version Control** Git enables every collaborator to own a full copy of the project and its history. This decentralization supports the open workflows of both open science and open source by allowing everyone to work offline and maintain redundancy. - +::::{todo} :::{figure} /images/github/image-coming-soon.png :alt: Alt here Graphic here showing a main repo and then numerous forks ::: - +:::: - **Collaboration Across Teams** Git makes it easy for multiple contributors to work on the same project. It provides tools to integrate changes, resolve conflicts, and ensure everyone's contributions are recognized—a key aspect of inclusive open workflows. diff --git a/github-git/your-first-contribution.md b/github-git/your-first-contribution.md new file mode 100644 index 0000000..496f58f --- /dev/null +++ b/github-git/your-first-contribution.md @@ -0,0 +1,193 @@ +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + 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. +--- + +# Mastering GitHub Collaboration Skills + +Contributing to open source in a public space like GitHub can feel intimidating. You may not know the project maintainers, feel unsure about your GitHub skills, or wonder where to begin. + +This lesson series will teach you how to collaborate on code and documentation using GitHub. It will help you confidently contribute to a GitHub repository and build skills to collaborate with colleagues (some of whom you may not have met in real life!). + +(first-contribution)= + +## Get started with your first open source contribution + +:::{admonition} What you will learn + +Completing this set of activities will give you the technical and social skills needed to collaborate and contribute to an open source GitHub +repository. You will use the [pyOpenSci example GitHub repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) as a safe space to practice making contributions. +::: + +This page introduces all of the steps and walks you through each one. Each activity below has a lesson that will help you understand the social and technical elements of the contribution process. + +## An overview of the collaborative GitHub workflow + +:::{figure} /images/github/steps-to-contribute.png +:alt: alt text here + +The steps for making your first contribution to an open source repo. In this lesson, you will do all of your work on GitHub.com, meaning you don't need to clone or make a copy of your repository locally. This is a great way to get started with contributing. It minimizes the command line skills that you will need to use git. +::: + +## A step-by-step guide to your first contribution + +### Step 1: Identify the repository and get to know it + +First, identify and get to know the repository you want to contribute to. Use the [pyOpenSci learning repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) to test out the process. + +[Getting to know that repository](get-to-know-repo) will save you and the maintainers time when you make your first contribution. You can think about like doing some research on a blog post before sitting down and writing it. + +Ideally, the repository you have chosen has documented the types of contributions they welcome and what process they want contributors to follow. Reading through that documentation first will help you get started quickly and minimize the questions you ask the maintainer team. Most often, the best place for a new contributor to start, regardless of their experience contributing, is the [contributing guide](https://www.pyopensci.org/python-package-guide/documentation/repository-files/contributing-file.html) and the [README file](https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html). + +:::{button-link} get-to-know-repo.html +:color: primary +:shadow: + + Learn how to get to know a GitHub repo +::: + +:::{admonition} Activity 1: Get to know the repository + +Open a new browser tab after reading through the [get-to-know a repo lesson](get-to-know-repo). Navigate to [https://github.com/pyOpenSci/pyos-demo-package-contribute/](https://github.com/pyOpenSci/pyos-demo-package-contribute/). + +* Review the [README](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/README.md) and [CONTRIBUTING](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/CONTRIBUTING.md) files. + +**Answer these questions** + +* Does the repository accept contributions? If so, what types of contributions are accepted? +* Are there existing issues open in the repository? Do those issues have labels? +* Is the contribution process documented in the repo? +* Does the repository use specific code or text formatting standards or liters? +* Does the repository have continuous integration (CI) set up? +* What is the license associated with the code in the repository? +* Are the issues labeled, and are there "good first issue" or "help wanted" labels +::: + +****** + +### Step 2: Find an issue to work on + +Next, [identify an issue or bug that you want to work on](identify-issue). Sometimes, there is already an open issue in a repo that you want to address. So, reading through existing open issues before opening a new one is always a good idea. If you already have a fix in mind that doesn't exist in the existing issue list, you will [create a new issue](create-issue) in the repo. + +:::{button-link} identify-issue.html +:color: primary +:shadow: + + Learn how to identify and open a GitHub issue +::: + +:::{admonition} Activity 2: Create an issue for a bug that you'd like to fix + +1. Navigate to the [pyOpenSci example repo](https://github.com/pyOpenSci/pyos-demo-package-contribute). +2. Explore the documentation and code. You will find many items that need to be fixed, including spelling errors, typos, and more. +3. Pick a file that you'd like to work on. Open a new issue specifying what you'd like to fix. +4. Wait for someone on the pyOpenSci team to respond to you with next steps. + +Once you have submitted an issue and someone has responded positively, you can begin working on the changes in your fork. [You will learn how to fork a repo next.](fork-repo) +::: + +****** + +### Step 3: Fork the repository + +Once you have created an issue or identified what you wish to work on, you will [`Fork` or create a copy of the repo](fork-repository) in your GitHub account. + +:::{button-link} fork-repo.html +:color: primary +:shadow: + + Learn how to fork a GitHub repo +::: + +:::{admonition} Activity: Fork a repository and modify a file + +**Fork the pyOpenSci practice GitHub repository** +******* +* Navigate to the [pyOpenSci example repo](https://github.com/pyOpenSci/pyos-demo-package-contribute). +* Fork the repository. + +*Remember that a fork is a copy of a repository that is owned by someone else or an organization that lives in your GitHub account.* +::: + +******** + +### Step 4: Edit and commit your changes + +Once you've successfully forked the repo, it's time to edit the file you want to fix. In this lesson, you are editing documentation files in the GitHub interface. This means that you don't need to set up a local development environment. + +:::{button-link} edit-commit-files +:color: primary +:shadow: + + Learn how to edit & commit files on GitHub +::: + +:::{admonition} Activity: Make a change to a file and commit it to your fork + +1. Navigate to your fork on GitHub.com +2. In the GitHub interface, click on the file that you proposed to modify or fix [in the identify issue lesson](identify-issue) +3. Click on the edit button in the GitHub interface. +4. Make the edits to the file that you proposed in your issue. +5. Hit the commit button to save your edits +6. Add a descriptive commit message that describes the change that you made + +Commit message examples: +> fix: fixed numerous typos in the filename.py file +> +> fix: updated the code to align with PEP 8 syntax +> +> fix: fixed typo in docstring text + +::: + +****** + +### Step 5: Submit a pull request + +Once your edits are [committed to git version control](edit-commit-files), open a Pull Request to the parent repository. + +:::{button-link} pull-request.html +:color: primary +:shadow: + + Learn how to create a GitHub pull request +::: + +:::{admonition} Activity: Submit a PR to the pyOpenSci parent repository +Create a Pull Request to the [pyOpenSci parent repository](https://github.com/pyOpenSci/pyos-demo-package-contribute), from the branch on your fork that you worked on in the previous lesson. +::: + +Once your PR is open, it's time to sit back and wait for the maintainers, collaborators, or project owners to review/comment on your PR. Be patient; this step can take time as people are busy and often donate their time to this effort! + +******** + +## Many people's first contributions are to documentation + +In this lesson, you make your first open source contribution by updating documentation (including docstrings) rather than code. Many people start with small fixes like typos, which are simpler to contribute as you don't always need a development environment but are still **highly valuable**. + +### Fresh eyes make a difference! + +When you’re new to a project, you may notice gaps and unclear explanations that long-time contributors might overlook. Maintainers and developers are often too close to their own work to see what’s missing. Your perspective helps make the project more accessible to future contributors. + +By catching confusing phrasing, outdated information, or missing details (even in contributing documentation), you improve the onboarding experience for others while making a meaningful first contribution! + + +:::{admonition} A real-life first contribution to PyPI + +[Here is an example issue that resulted in 2 small pull requests to PyPI (warehouse)](https://github.com/pypi/warehouse/issues/17374). In this case, the images were outdated, so it was a bug in the documentation that needed to be fixed. However, while getting to know the repository, the author also found issues with the development documentation, so they submitted a pull request to address that as well. Both pull requests were small. +::: diff --git a/images/github/contribute-no-fork.gif b/images/github/contribute-no-fork.gif new file mode 100644 index 0000000000000000000000000000000000000000..d2be78ea0b8d5ed763f2866f5145959204063b70 GIT binary patch literal 3596199 zcmWh!WmwZ+8~$x;hao0z6!bJe<6OV!T)>aak2PVIdiDSw(4aSve&RNmFiB zPYHP(pNfO5vKB_;8n=-ckC`N&r4-gnLHwq=nzjj_Ubs}OrXDl189#@Ph=7iaxUPzl zy^x@bw3wZ`BA)MxucWx1hPJV$hMktGzma;ZzLc(kiJpnInYF2@m7|@3zP+intEGXZ zovWR*mxE2Ti>LoJV_i=x6CXSK5JTN?OQV}kcK$BjA#NW29q9cpK1FK@f>iAL> zB(ia`X*x>zh8o2d`uFTD%H6Fh@D4S;zA3Tz`XJxt@EaX*p`8h8iR&6^9|F?}aY>nx z`I+(e3Zi?Hwex=_OG>6%Dy7()q`TPPvo|eswa&pCX5(#2uQ?@O_aWX0O9>51jf}b* z;B)6@KvDFq>Hw$u2%m=No81xqJ#jbJLY>~-^7x+Moe`Uqm~gKkJ~=6_IfoEil$21L z6g`j}xtilLnI7}}PVCF`ai3dx|S|-PjgGxKyO`rUrWzOcWY<=aCO;uW6g9|+ic(P#PGmU z&R9voKQdcw9-ZM4WyWUd!rn7#lJb$My>qEnxotCQYuKJ0g>50*oPsSfk%siW!e=+%P zc7A#7)!gLL!rS*R7nWAvE-h@n+Ss1moPYLV>DAurjqSbN_p6)l_qRSB?H+#L`@Vm4 z^6U8P>G97$a0&o|a~gDz$CKd9A}+HXm6K^GKBET)omJCW?6TK4W;?5A@-W(&oQ7RB zPYSWtO)gKmYM+)!dCfgA?5=xuU+L!l#*^;)=M}gl1eZ}y!&0?Dp@{2TPveVvi)y1X zqu!>M%?{ny-_G?mueReSGr5fWT3&biy=ZcM+SmG~Kjgz)nQ?#H+lNsn`){B2x4(Zx zph9w+40LQwrZbDW%@1^bm?7~QmzxZB?K~}&4R|*{*!}4_Sv!l{bg1X^iw5gvw`W7W z2df=kPs>do_8q+$xOwpI*~9*?@5hpmSImY7zI~W26m?%19z6N9SZ!QkHZpX2u+|;$ zeqrR{+1Jgo*R?{=iKYX#OBfKv^Ad{Q4jl)C5%0DSF%x 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