Repository for practicing and learning GitHub at OSACC 2024. GitHub is a tool for managing contributions to an open source project. You can use it to keep track of different versions of your code, track issues, plan projects, and write documentation (among other things). In this workshop, we'll cover some basics of getting to know GitHub:
- browsing and filing issues
- checking out and modifying your own copy of the code
- submitting a pull request to resolve an issue
Issues are used to track bugs, feature requests, and other tasks in a project. Community members may be assigned an issue, indicating that they are responsible for fixing or otherwise taking care of it. Issues may also be organized using labels—sometimes, a project may have a label to help new contributors find issues that are easier to fix to encourage them to join the project.
You can view existing issues under the Issues tab. Browsing open issues is a great way to get to know a project. If you think you've found a bug in a project, it's a good idea to search the open issues to see if anyone else has already reported the issue. This not only prevents you from filing a duplicate issue (creating more work for the maintainer of the project), but also may allow you to find a workaround to the issue submitted by another community member before a solution is published by the maintainers.
To open a new issue, click on the Issues tab and then find the green New Issue button. Write a description of your proposed changes or the bug that you found.
When filing a bug report, it's important to include:
- the expected outcome (a description of what you think should have happened)
- the actual outcome (what happens instead of what you expected)
- steps to reproduce the problem, as succinctly as possible
- any other information the project asks for (e.g. what browser and/or operating system you are using when you encounter the bug)
Many projects have a template for filing a new issue, which will describe their guidelines for submitting a good issue report. Be sure to follow their instructions!
When filing a feature request, it's important to include:
- a description of the change or new feature you'd like to see
- why you think it is beneficial to the project
Issue templates are useful for making sure users add required information to bug reports and feature requests. Information for creating an issue template is at this GitHub Documentation Page
- Install git on your computer
- Create a directory folder on your computer (example: Desktop)
- Navigate to your directory in your terminal (cd command)
- On the Github repository page, click on the green Code button, and copy the HTTPS url address
- Back in terminal, write the following command:
git clone [insert HTTP url address here]
- Now that your github repo is cloned to your local computer, open the cloned local folder using your code editor of choice (example: VSCode, IntelliJ)
- Start making some changes to the code
Why edit your code in the browser?
- Convenience: Modify your code from virtually any device! If you're using a public computer, own a device without the bandwidth to download the project or simply want to use smaller devices like iPads and tablets, coding from the web may be for you.
- As a bonus, everything autosaves on the web, so feel free to step away and return to your project without fear of losing your hard work!
- Privacy: Concerned about the privacy and security risks associated with downloading to your personal device? Working in the browser may be the route for you!
- Sustainability: You can turn off the VM, which both saves energy and potentially saves you money (learn more below)
Many users will want simply leverage GitHub's built in online code editor called Codespaces. Simply click on Code
.
Click Codespaces
.
Make a new environment (either click the plus or the large green button)
.
In addition to Codespaces, you may interact with repositories outside GitHub and Gitpod is similarly an application that allows users to open and edit Git repositories on the go without local downloads. To start, register and link you Gitpod account to your Github here: https://www.gitpod.io/. Once completed, you will be asked to input the link to your Git repository and desired code editor. And now, you are free to edit on the go with anything!
In either case, the code editor is running a full fledged machine in the cloud! If you click on terminal at the bottom of the screen, you can even execute commands.
When you are ready to send up your changes, you can open a new branch
.
Then, make a commit on the left side of the screen.
.
When you are done, click on codespaces (or equivalent) in the bottom left to and click "Stop Current Codespace" or "Stop Current VM" to turn off the machine in the cloud that is running your code editor. You can come back to it later! However, after some time (a few days) it will be deleted.
Click the "Fork" button on the top right of the project page to make a copy of the project to your own GitHub account.
Navigate to the original repository where you created your fork.
Above the list of files, in the yellow banner, click Compare & pull request to create a pull request for the associated branch.
On the page to create a new pull request, click compare across forks. In the "base branch" dropdown menu, select the branch of the upstream repository you'd like to merge changes into. In the "head fork" dropdown menu, select your fork, then use the "compare branch" drop-down menu to select the branch you made your changes in. Type a title and description for your pull request. On user-owned forks, if you want to allow anyone with push access to the upstream repository to make changes to your pull request, select Allow edits from maintainers. To create a pull request that is ready for review, click Create Pull Request. To create a draft pull request, use the drop-down and select Create Draft Pull Request, then click Draft Pull Request.