|
| 1 | +--- |
| 2 | +jupytext: |
| 3 | + text_representation: |
| 4 | + extension: .md |
| 5 | + format_name: myst |
| 6 | + format_version: 0.13 |
| 7 | + jupytext_version: 1.16.4 |
| 8 | +kernelspec: |
| 9 | + display_name: Python 3 (ipykernel) |
| 10 | + language: python |
| 11 | + name: python3 |
| 12 | +myst_html_meta: |
| 13 | + "title": "How to edit and commit changes to a file on GitHub: Intro to Collaborative GitHub" |
| 14 | + "description lang=en": "Learn how to edit a file and then commit changes to that file to version control. All in the GitHub interface." |
| 15 | + "keywords": "GitHub, OpenSource, beginner-friendly" |
| 16 | + "property=og:locale": "en_US" |
| 17 | +og:image: /images/github/steps-to-contribute.png |
| 18 | +og:image:alt: An image that shows the steps for contributing to open source on GitHub. |
| 19 | +--- |
| 20 | + |
| 21 | +# Your First Edits to a File in Your Fork: Edit & Commit |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +> **💡 Reminder:** Your fix should be **small and text-based**, like updating documentation or fixing a typo. |
| 26 | +
|
| 27 | +:::{admonition} What you'll learn |
| 28 | +:class: tip |
| 29 | +You’ll edit a file directly in your **fork** using GitHub’s interface and commit the changes using only the native GitHub interface. |
| 30 | + |
| 31 | +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). |
| 32 | + |
| 33 | +::: |
| 34 | + |
| 35 | +## How to edit a file in your fork |
| 36 | + |
| 37 | +GitHub lets you edit files right in your browser. Here’s how: |
| 38 | + |
| 39 | +1. Navigate to **your fork** of the repository. |
| 40 | +2. Find the file you want to edit. |
| 41 | +3. Click the <kbd><i class="fa-solid fa-pencil" style="color: #81c0aa;"></i> Edit</kbd> button. |
| 42 | +4. Make your changes and **commit** them. |
| 43 | + |
| 44 | +:::{figure} /images/github/edit-commit-file.gif |
| 45 | +:alt: "GIF showing how to edit and commit a file on GitHub." |
| 46 | + |
| 47 | +Editing a file directly in the GitHub interface is a straight forward process. |
| 48 | +::: |
| 49 | + |
| 50 | +> **⚡ 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. |
| 51 | +
|
| 52 | + |
| 53 | +## Ways to edit a file: GitHub vs. GitHub Codespaces |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +| | Option | When to Use | Pros | Limitations | |
| 58 | +|-|---------|------------|------|-------------| |
| 59 | +| | **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 | |
| 60 | +| | **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 | |
| 61 | + |
| 62 | +> **💡 Need to edit multiple files using a coding editor like VsCode or Jupyter?** Learn more about using [GitHub Codespaces](github-codespaces). |
| 63 | +
|
| 64 | +## What is a commit? |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +:::{tip} |
| 69 | +A **commit** is a feature of [git version control](what-is-git), the version control system that GitHub runs in the background. |
| 70 | + |
| 71 | +::: |
| 72 | + |
| 73 | +### How commits work |
| 74 | + |
| 75 | +:::{figure} /images/github/git-commits-files.png |
| 76 | +: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. |
| 77 | + |
| 78 | +Each commit represents **a set of changes** at a specific time. |
| 79 | +::: |
| 80 | + |
| 81 | +> **🛠 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. |
| 82 | +
|
| 83 | + |
| 84 | +:::{figure} /images/github/git-what-are-commits.png |
| 85 | +: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.” |
| 86 | + |
| 87 | +You can always **undo or revert** changes using Git. |
| 88 | +::: |
| 89 | + |
| 90 | +:::{admonition} What's next? |
| 91 | +:class: seealso |
| 92 | + |
| 93 | +<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. |
| 94 | + |
| 95 | +***** |
| 96 | + |
| 97 | +[Learn how to create a pull request →](pull-request) |
| 98 | +::: |
| 99 | + |
| 100 | + |
| 101 | +:::{todo} |
| 102 | + |
| 103 | +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. |
| 104 | +::: |
0 commit comments