|
| 1 | +--- |
| 2 | +title: "Github Guide" |
| 3 | +description: "Github usage for open source contribution" |
| 4 | +draft: false |
| 5 | +menu: |
| 6 | + curriculum: |
| 7 | + parent: "curriculum-intro" |
| 8 | +weight: 80 |
| 9 | +category: lecture |
| 10 | +levels: |
| 11 | + - shallow |
| 12 | + - deep |
| 13 | +--- |
| 14 | + |
| 15 | +{{< embed src="https://docs.google.com/presentation/d/11V_BA5A64lCY_wFsvuLO4je02zvzJwD5vf2kzONDWyc/embed" width="100%" height="600px">}} |
| 16 | +_[Github Deck Link](https://docs.google.com/presentation/d/11V_BA5A64lCY_wFsvuLO4je02zvzJwD5vf2kzONDWyc/edit?usp=sharing)_ |
| 17 | + |
| 18 | +## Tutorial – Contributing to OSS on Github |
| 19 | + |
| 20 | +In this tutorial, you will learn how to use the GUI to open an issue, create a fork, and make a PR to any repo on Github. |
| 21 | + |
| 22 | +### Part 1: Create an Issue |
| 23 | + |
| 24 | +Issues are super easy ways for you to make a suggestion to an OSS team, without having to ping them personally. These issues are then housed in a place that makes it easy for them to organize, review, and assign to others. |
| 25 | + |
| 26 | +- Open a repo. In this example, I will use the [Launchpad Repo at https://github.com/protocol/launchpad](https://github.com/protocol/launchpad). |
| 27 | + |
| 28 | +- Click on the 'Issues' tab to go to the page to submit Issues: |
| 29 | +  |
| 30 | + |
| 31 | +- Click on the **New Issue** button, choose an issue template, and click the **Get started** button to open up a template. |
| 32 | +  |
| 33 | +  |
| 34 | + |
| 35 | +- You can delete all of the writing underneath the bold headers. Bold headers have two stars `**sentence text**`, and you can write anywhere beneath those bold headings. Not all fields are mandatory! |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +- Click **Submit new Issue** and you can go back the the issues tab and see it on the list! |
| 40 | + |
| 41 | +Now the team who maintains that repo can see any problems you want to report, assign, and track who can see it. You will also get e-mail notifications for any responses people have to you. Using `@username` in a comment, Issue, or PR will notify that particular person. |
| 42 | + |
| 43 | + |
| 44 | + |
| 45 | +### Part 2: Make a PR in the GUI |
| 46 | + |
| 47 | +If you want to take your changes to the next step, you can fork the repo and make a Pull Request (PR). This will make it as easy as the click of a button for repo maintainers to add in your suggestions. |
| 48 | + |
| 49 | +### Modify an Existing File |
| 50 | + |
| 51 | +#### Make a Fork |
| 52 | + |
| 53 | +- First, go to the repo and choose the **Fork** button on the top right |
| 54 | +  |
| 55 | + |
| 56 | +- A new fork (version with the same history) of that repo will be created under your organization or username. |
| 57 | + |
| 58 | + |
| 59 | + |
| 60 | +> Note that any time you go in and make changes, you will want to make sure that your repository is up to date with the original repo. You can do this from the main page of your repository fork with the **Sync fork** button. |
| 61 | +
|
| 62 | + |
| 63 | + |
| 64 | +#### Make an Edit |
| 65 | + |
| 66 | +- Now you have to find which file you want to modify. In the repository used in this example, `launchpad`, all of the content is in the directory `content/en`. |
| 67 | +  |
| 68 | + |
| 69 | +- Compare the directory structure with the URL of the curriculum and find a page you would like to make a small edit on. Note that the file you need to edit will either have the same name as the file in the URL (e.g. how-filecoin-works.md), or be an `index.md` file inside of a directory with the same name as you see in the URL. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +- Click the Pencil Icon at the top of the page preview. From here you can make the edits you would like to that page. |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +- Once you have completed your edits, you should click the **Commit changes** button, add a short description, and choose **Commit Directly to the main branch** then click the **Propose changes** button to merge the change into your remote repository. |
| 78 | +  |
| 79 | + |
| 80 | +When you go back to the home page for the repo, you should see your commit listed: |
| 81 | + |
| 82 | + |
| 83 | + |
| 84 | +#### Make a PR |
| 85 | + |
| 86 | +Now that you have these changes on _your_ remote Github repo 'packaged up', you are ready to make a Pull Request to the _original_ remote repo. |
| 87 | + |
| 88 | +- You can propose those changes (make a pull request) to the original Launchpad curriculum repo that you forked from. Go back to the [original Launchpad repo](), and go to the Pull Requests tab. |
| 89 | +  |
| 90 | + |
| 91 | +- Now you can create a PR! In the Pull requests page, choose **New pull request**, then choose **compare across forks** |
| 92 | +  |
| 93 | +  |
| 94 | + |
| 95 | +- In the Comparing Change page, choose your head repository (and `main` branch) on the right side of the comparison, the click **Create Pull Request**. |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | +- On the next screen, you should see the same details show up for the commit you had made on your remote repo. Add more details if you wish, then click **Create Pull Request**. |
| 100 | + |
| 101 | +- Now when you check the [Pull Request for the Launchpad repo](https://github.com/protocol/launchpad/pulls) you can see your new Pull request, and make it easy for maintainers to explore and commit the changes! |
| 102 | +  |
| 103 | + |
| 104 | +The maintainers of these repos only need to push a button to confirm the merge, making it much more likely (and easier for the maintainers) to get changes added. |
| 105 | + |
| 106 | +### Add a new File |
| 107 | + |
| 108 | +Adding a new file is simple in the Github CLI. You can test this out in the fork you created. Lets add a new Dev Tool (any project or company you know of in PLN) to the Dev Tools section! |
| 109 | + |
| 110 | + |
| 111 | +- First, remember to sync with the original repo! |
| 112 | +  |
| 113 | + |
| 114 | +- Now, you can navigate into `/content/en/curriculum/dev-tools` and click **Add file**. From here you can add a new markdown file (like `spice.md`) about the Dev Tool you know about. |
| 115 | +  |
| 116 | + |
| 117 | +See the Markdown guide below for how to author. Remember you will have to follow the same workflow as above where you first push to your own fork, then open a PR in the [original Launchpad curriculum repo that you forked from](https://github.com/protocol/launchpad). |
| 118 | + |
| 119 | +You can also take a look at the [tutorial-temp.md file](https://github.com/protocol/launchpad/blob/main/tutorial-temp.md). Click the **Raw** button to see a markdown template that you can copy-paste into a new file. |
| 120 | + |
| 121 | + |
| 122 | +<!-- ### Part 3: Make a PR using the CLI --> |
| 123 | + |
| 124 | +## Guides |
| 125 | + |
| 126 | +### Markdown Guide |
| 127 | + |
| 128 | +Every text input section in [GitHub uses Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github). Every Pull Request (PR), review, issue, and comment section supports markdown. Markdown is not specific to Github, but is it's own writing and formatting style. Github has added additional functionality to it that is only usable within Github like interacting with other users with @mentions, issue and PR references, and emoji's! |
| 129 | + |
| 130 | +If you are contributing to open source repositories and organizations, here are some common uses seen in the wild: |
| 131 | + |
| 132 | +<!-- This table was generate with https://www.tablesgenerator.com/markdown_tables --> |
| 133 | + |
| 134 | +| Markdown | Command | Description | |
| 135 | +| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ | |
| 136 | +| HEADER | # | Used for headings, add more symbols before the heading to change the size from 1 (biggest) to 6 (smallest). | |
| 137 | +| \* unorderedList | \*/- | Either a single `*` or `-` is used for _unordered lists_. Tabs create sub-lists. | |
| 138 | +| 1) numberedList | number) | Used to create _numbered lists_. Tabs create sub-lists. | |
| 139 | +| > Quote | > | Used to quote other users responses. | |
| 140 | +| \`code\` or \```codeblock\``` | \` | A single ` is used for just one line of code. A group of three ``` are used for multi-line code blocks. | |
| 141 | +| \[title\]\(www.example.com\) | \[ ] ( ) | Create URLs/Links in this format. With the text you want to display `[]` and the URL in `()` | |
| 142 | +| :thumbsup: | :emoji name: | Write the emoji name in between colons to create an emoji. | |
| 143 | +| :white_check_mark: Checklist | [] | Github automatically creates a progression bar for checkboxes grouped together within Issues. | |
| 144 | +| @username | @ | Github will create a link to the user and notify them (with respect to their preferences). | |
| 145 | +| #GHIssueNumber or PRNumber | # or GH- | Github will automatically create a link to an Issue or PR, IF applicable. Else, it'll treat it like Heading. | |
| 146 | + |
| 147 | +Source: [Github Writing Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), [Markdown Guide](https://www.markdownguide.org/cheat-sheet/) |
| 148 | + |
| 149 | +### Github Orgs & Repos |
| 150 | + |
| 151 | +There are a number of different Open Source Software (OSS) organizations and projects that are used to manage the code that makes up what we maintain at Protocol Labs. |
| 152 | + |
| 153 | +Everything created at PL is open source. To get to the organization or repo, just type in `github.com/<organization>/<repo>`. |
| 154 | + |
| 155 | +Explore some of the most active repositories below to learn about the projects. |
| 156 | + |
| 157 | +- **Protocol Labs** – /protocol: [https://github.com/protocol](https://github.com/protocol) |
| 158 | + - Repos: [specs](https://github.com/ipfs/specs), [CI Workflows](https://github.com/protocol/.github), [launchpad](https://github.com/protocol/launchpad), [Infrastructure](https://github.com/protocol/launchpad), [Research](https://github.com/filecoin-project/devgrants), [/bifrost-infra](https://github.com/protocol/bifrost-infra), [/monitoring-infra](https://github.com/protocol/monitoring-infra), [/netops](https://github.com/protocol/netops) |
| 159 | +- **IPFS** – /ipfs: [https://github.com/ipfs](https://github.com/ipfs) |
| 160 | + - Repos: [/kubo](https://github.com/ipfs/kubo) , [/ipfs-desktop](https://github.com/ipfs/ipfs-desktop),[specs](https://github.com/ipfs/specs), [ipfs-companion](https://github.com/ipfs/ipfs-companion) |
| 161 | +- **IPLD** – /ipld: [https://github.com/ipld](https://github.com/ipld) |
| 162 | +- **libp2p** – /libp2p: [https://github.com/libp2p](https://github.com/libp2p) |
| 163 | + - Repos: [/specs](https://github.com/libp2p/specs), [/rust-libp2p](https://github.com/libp2p/rust-libp2p), [/js-libp2p](https://github.com/libp2p/js-libp2p) |
| 164 | +- **Filecoin** – /filecoin-project: [https://github.com/filecoin-project](https://github.com/filecoin-project) |
| 165 | + - Repos: [/bacalhau](https://github.com/filecoin-project/bacalhau), [/FIPs](https://github.com/filecoin-project/FIPs), [/lotus](https://github.com/filecoin-project/lotus), [/devgrants](https://github.com/filecoin-project/devgrants), [/community](https://github.com/filecoin-project/community) |
| 166 | +- **Other PLN Projects** |
| 167 | + - Testground -[https://github.com/testground](https://github.com/testground) |
| 168 | + - Saturn – [https://github.com/filecoin-saturn](https://github.com/filecoin-saturn) |
| 169 | + - Drand - [https://github.com/drand](https://github.com/drand) |
| 170 | + - Boost – [https://github.com/filecoin-project/boost](https://github.com/filecoin-project/boost) |
| 171 | + - CryptoNet Lab – [https://github.com/protocol/CryptoNetLab](https://github.com/protocol/CryptoNetLab) |
| 172 | + - CryptoEcon Lab – [https://github.com/protocol/CryptoEconLab](https://github.com/protocol/CryptoEconLab) |
| 173 | + - Bacalhau / COD – [https://github.com/filecoin-project/bacalhau](https://github.com/filecoin-project/bacalhau) |
| 174 | + - Network Indexer – [https://github.com/ipni/storetheindex](https://github.com/ipni/storetheindex) |
0 commit comments