Contributing to repos
Now that we know the bare basics of using git, let's collaborate with other developers on the GitHub platform.
Head over to Admin2Dev Learning Markdown Repo and on top right, click on Fork. To Fork a repo means to creating an instance of the repo for your use, this is different from cloning a repo since that downloads from the server to our device.
Notice how it says
forked from Admin2Dev/learning-markdown right under the repo name on top left. What we have done at this point, is created an instance of the repo for ourselves. By doing this, we can work on this repo
however we want without affecting the original repo.
Let's make some changes. In our README.MD, let's add an extra line at the end and commit it. You can either use the edit button on GitHub or clone the repo on your machine and add/commit/push.
> May the Salesforce be with you!
A pull request from a fork is notifying the repo owner to look into changes you've made, and add it to the main repo. In this case, I am asking Admin2Dev, owner of the learning-markdown repo, to merge my changes into their repository, so everyone who visits the repo sees this version.
Let's click on the Pull Request and submit a request.
You'll notice it lists all changes made, along with a screen that compares what changes were made. In this case, we see a green line with our pun in it, indicating we added a new line in the README.MD file. Go ahead and click on Create Pull Request and then explain what changes were made. This is particularly important because you need to document what changes you made to the codebase and why you made it.
Now let's switch to Admin2Dev's (now referred to as A2D) side. A2D gets a notification that a new Pull Request was opened by kinngh to their learning-markdown repo.
Upon opening the notifcation, A2D is taken to the Pull Request page where they can see what changes were made, commit messages, who made the commits and other relevant info
Once they confirm the merge, the Pull Request will be closed and the status will be updated to Merged, and the code base was updated with the commit message
Merge pull request #1 from kinngh/master. You can now
safely delete the original fork you made.
You can look at the git repos here:
A lot of Open Source projects will have a file called CONTRIBUTING.md in their repo which outlines how you should be contributing. This includes ensuring tests are passed (like writing Test Classes for Apex), code is formatted using a specific linter, among other guidelines. You can take a look at Alamofire/Alamofire repo's CONTRIBUTING.md that outlines how to ask questions, reporting issues, reporting security issues, basic code of conduct, etc.
It's a good practice to follow pointers in a repo's CONTRIBUTING.md file before opening issues or pull requests.
Not every piece of code on GitHub is available for commercial use, or even open source for that matter. A lot of projects post their codebase on GitHub for transparency purposes, which is why it's always a good idea to look into the LICENSE.MD file of a repo, and actually following it. GitHub does a great job of detecting licenses and showing a quick summary of how the repo can be used, like this one from plausible/analytics
Below is a list of sites you can read about the licenses in depth:
- Understanding Open-Source and Free Software Licensing on Medium
- Open-source license on Wikipedia