Skip to content

Latest commit

 

History

History
225 lines (140 loc) · 13.6 KB

vi-github-issues.md

File metadata and controls

225 lines (140 loc) · 13.6 KB
Raw

GitHub Issues (Step 6)

Estimated Time: 2.5h

1. Objectives

  • Learn about GitHub Issues, Commits, and Pull Requests
  • Understand the collaborative git/GitHub workflow used during the internship
  • Create an GitHub Issue regarding Software Engineering Intern First Steps' content, then create a branch to fix it upon approval
  • After resolving the Issue, make a Pull Request to the open-learning-exchange/open-learning-exchange.github.io upstream repository
  • Work with us to make necessary changes, then merge the branch into the upstream repository
  • Comment on an existing Issue

2. Introduction

GitHub repositories have a section for Issues, where problems can be categorized, discussed, and fixed. Issues are often opened by our team members to create new features or fix bugs in our projects. This tutorial guides you through the process of creating Issues, branching, making Pull Requests, and collaborating with team members.

We encourage you to file as many issues as possible, whether large or small. If you spot a problem but don't know how to solve it, file an issue so others are aware and can work on a solution. Aim to add as much value as possible with your issues, as this helps support the community and enhances the overall quality of this MDwiki site.

NOTE: Issues are not just about adding new content or improving this MDwiki; they can also involve removing redundant or unnecessary material. The goal is to keep the documentation clear and concise. If you find sections that could be simplified or reduced, feel free to create an issue to help streamline the process.

3. Create an Issue

If you've noticed an area for improvement in the Software Engineering Virtual Intern First Steps content, let's address it! If not, take a look around to find an issue; remember, it can be big or small. Once you've identified an issue, begin by checking existing issues labeled with vi, both open and closed to ensure it hasn't been raised before or already addressed. If it hasn’t, go ahead and create a new issue:

  • Go to the Issues tab of the upstream repository and select "New Issue." Select the "Get started" button next to "First Steps - Software Engineering Virtual Intern."
    1. Craft a succinct, descriptive title.
    2. Complete the issue template thoroughly, ticking all required checkboxes and providing necessary details.
    3. Drop a link to this issue in our Discord channel.
  • You can reference this example to see how an issue follows the issue template with a clear structure.
  • Once submitted, others can provide feedback to guide next steps. If replying to a comment on an issue, please notify the commenter in our Discord channel.

Note: While creating a Pull Request doesn't require prior approval, it's best to wait for confirmation of the issue from our team before working on a fix. If your suggested changes don't align with project goals, your Pull Request might not be merged, and your work won't count toward "First Steps" progress. By seeking approval first, you can avoid wasted effort and rework.

Existing Issues: You can also work on existing issues. If an issue is labeled vi and first step intern, you can request to work on it by messaging us in Discord. If someone else is already assigned or has stated their intent to work on it in the issue's comment section, don't work on that issue; choose another one instead.

Special Note:

  • Interns often rush through this process to complete their "First Steps." Remember that these steps aim to fix genuine problems and improve the workflow. Take time to examine the "First Steps" materials to find real issues and research the best solutions. Also, ensure the issue hasn't already been identified.

4. Synchronize Your Repository

Before you create your branch, sync your repository with the following commands (as we walked you through in the previous step):

  1. Fetch the latest changes from the upstream repository:

    git fetch upstream

  2. Switch to your master branch:

    git checkout master

  3. Merge the fetched changes from the upstream master branch into your local master branch:

    git merge upstream/master

  4. Push the updated master branch to your forked repository on GitHub:

    git push origin master

ATTENTION: From now on, for the rest of the First Steps, please use the command line to create branches and make commits instead of using GitHub’s web interface. This will give you valuable practice with common Git commands in your terminal, which is essential for working on real code that needs to be tested locally and can’t always be edited directly on GitHub.com.

5. Create a New Branch

Every time you start to work on an issue, you need to create a branch to keep issues you are working on separated from each other. Make sure to use a descriptive name for your branch in the following fashion: issueNumber-descriptive-branch-name.

  • To create and switch to a new branch from master, run the following commands:

    git checkout master  # Ensure you are on the master branch
git checkout -b <issueNumber-descriptive-branch-name>

    Make sure to replace <issueNumber-descriptive-branch-name> with your actual branch name, without the angle brackets (< and >).

More documentation on git checkout can be found here.

Now you can go and make the proposed changes to your local files using any text editor you prefer. You can also use VIM or Nano to edit files from the terminal. This guide on VIM and this guide on Nano contain more information on their proper usage. In the future, we recommend you use Visual Studio Code for Planet, VIM for treehouse, and Android Studio for Android development.

NOTE: Use git branch to see which branch you are in. Your master branch is the base working branch. It needs to remain untouched just in case you need to revert some changes back to a working version. Make sure you are on right branch using git checkout <branch-name> while making proposed changes to your local files and while committing.

If you're still confused, that's quite alright. Forking Workflow can be quite challenging at first. See the diagram below. For better context, the new branch you just made is inside your "Forked GitHub IO".

GitHub Repo Flowchart

5.1. Preview Changes Locally

Before committing your local changes, you may want to preview how they are rendered on MDwiki locally. Optionally, you can set up a local HTTP server. To do this, navigate to your forked repository and run one of the following commands:

  • With Python 3: python3 -m http.server 8080
  • With Python 2: python -m SimpleHTTPServer 8080
  • With node.js http-server server: follow the MDwiki's guide here.

6. Create a Commit and Push the Changes

NOTE: Before making your commit, configure the email address you associate with your Git commits by following the instructions in Setting your commit email address in Git - GitHub Docs.

Use the following commands to commit and push your changes:

  1. Check which files in the working directory have been modified:

    git status

  2. Display file(s) changes:

    • To show specific file(s) change:

      git diff <file1> <file2> <file3>...

    • To show all file(s) change:

      git diff

    Verify the changes you made, then proceed to the next step. To understand git diff output, checkout Git Diff | Atlassian Git Tutorial.

  3. Stage the modified files:

    • To stage specific modified files:

      git add <file1> <file2> <file3>...

    • To stage all modified files show up in git status:

      • Caution: Before using this, double-check the modified files listed in the previous step to ensure you are not inadvertently staging unwanted changes.
      git add .

  4. Commit the staged changes with a descriptive message:

    git commit -m "<your_commit_message>"

    (Refer to the commit message guidelines below).

  5. Push the changes to your new branch on GitHub:

    git push -u origin <issueNumber-descriptive-branch-name>

    For any further commits on the same branch after the first one, you can simply use:

    git push

HINT: If you feel like you've messed something up with Git commands, check out Dangit, Git!?! for common mistakes and their fixes.

6.1. Commit Message Style Guide

Because the commits you will be making on this markdown wiki are fairly basic, it is not necessary to enforce a wordy commit style. However, in the future, when you start to work on more complex projects, it is helpful to write your commit messages in a certain way. Here is an article on how to write good commit messages.

For edits to this markdown wiki, we recommend that your commit messages only consist of the subject line (refer to the article for more on what the subject is).

  • Limit the subject line to 50 characters
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line

Here is an example of how you would write your commit message: $ git commit -m "add commit message style guide and add raw.githack section (fixes #841)"

HINT: In your commit message, if you add a keyword like "fixes" or "resolves" followed by "#" and the issue number, once your pull request is merged, the issue will automatically be closed. This is helpful because it helps declutter the issues section. See more here.

6.2. Raw.githack

Raw.githack is an important aspect of the pull request process. After you commit changes to your local branch and push them to your remote branch, you can view these changes by going to https://raw.githack.com/<YourUsername>/<YourUsername>.github.io/<YourBranchName>/index.html#!pages/vi/vi-first-steps.md and navigating to the page(s) you have changed. If everything looks correct, you are ready to create a pull request.

For example, https://raw.githack.com/xyb994/xyb994.github.io/add-xyb994-profile/index.html#!pages/vi/vi-first-steps.md will land in the First Steps – Software Engineering Virtual Intern's main page:

vi first steps main page with raw.githack link

Raw.githack makes it easy to see what the page will look like if your branch is merged, so don't forget to include a raw.githack link in your next step, the pull request.

7. Create a Pull Request

Now follow the instructions on GitHub Pull Request Tutorial to create your pull request.

NOTE: Remember to always sync your fork before starting to work on a new issue. To sync your fork you can go back up to Step 4 of this page or follow the summary section in the previous step.

This is an exercise to help you familiarize yourself with GitHub issues, committing, and creating pull requests. This is a common process in large open source projects as there is always room for improvement. So, we strongly encourage you to follow this process and continue to post issues and resolve them.

8. Comment on an Existing Issue

You will need to make at least one comment on an issue you did not create.

9. Useful Links

10. Track Your Progress

  • Once you complete Step 6 you will have:
    • 2 pull requests made (one at step 3 and one at step 6)
    • 1 comment added (on an issue you didn't create)
    • 1 issue created

Hint: You can track your progress with the number of pull requests and issues here.

→ Next: Step 7 - Nation Planet

Return to First Steps