Logo Created with 💖 By CandidDeer
Would you like to become a maintainer on this project and help keeping it going? If you are interested, read the maintainer's guide and send me a DM on Twitter.
This tutorial is also available in other languages
| English | Bangla | | :---: | :----: | :----------: |
Translations for projects documentations are welcome. Read
Translation Guideto contribute.
Here we will learn how to contribute in this project or in GitHub/Git with Terminal. This is a tutorial to help first-time contributors to participate in a simple and easy project.
- Setup
- Step 1 Fork This Repository
- Step 2 Clone the repository
- Step 3 Create a new branch
- Step 4 Open the index.html file
- Step 5 Copy the card template
- Step 6 Apply your changes
- Step 7 Commit your changes
- Step 8 Push your changes to github
- Step 9 Submit a PR(Pull Request)
- Step 10 Celebrate
- Next Steps
- Aknowledgements
First let's get setup to do the work. If you're not good with the command line interface here is the GUI tutorial using github desktop
- If you don't have git, install it from here
- The objective here is to make a copy of this project and place it in your account.
- A repository (repo) is how a project is called on GitHub and a fork is a copy of it.
- Make sure you are on the main page of this repo.
| Click on the Fork button |  |
|---|
- You now have a complete copy of the project in your own account.
Now we want to make a local copy of the project. That is a copy saved on your own machine.
- Now clone this repo to your machine. Click on the clone button and then click the copy to clipboard icon.
- A repository (repo) is how a project is called on GitHub and a fork is a copy of it.
Open a terminal and run the following git command:
git clone "url you just copied"For example:
git clone https://github.com/$Username/Contribute-To-This-Project.gitwhere $Username is your GitHub username. Here you're copying the contents of the first-contributions repository on GitHub to your computer.
Change to the repository directory on your computer (if you are not already there):
cd Contribute-To-This-ProjectNow create a new branch using the git checkout command
git checkout -b your-new-branch-nameFor example:
git checkout -b add-$Username-cardNote: Change $Username with your GitHub account Username.
Do NOT work on the master branch
- Now you have created a new branch separate from the master.
- For the next steps make sure you are working in this branch. You will see the name of the branch you are on at the bottom left of the text editor youre using where it says
$Username-cardas your branch name.
Now we need to open the file we are going to edit with your favourite code editor. We are using VSCode as our preferred code editor.
- The
index.htmlfile is directly in theContribute-To-This-Projectfolder. - Now you have the file you are going to edit open in your editor and you are ready to start making changes to it.
- You can open the file with the following command:
code index.htmlNote: This is a terminal code to open the file: index.html in VSCode.
We will now make a copy of our card templates and make changes to it
- At the top of the html file, under the
<head>and<header>sections you will find the section labelled== TEMPLATE == - Copy everything within the red square in the image, from the
Contributor card STARTcomment to theContributor card ENDcomment
- Paste the whole thing directly below the comment indicating it
- Make sure there is a single line of space between your card start and the last card end. It's good practice to keep our code as clear as possible
- Never use a linters or style formatters. The project has Prettier setup
- This now is your card for you to customize and edit.
We'll now start editing html, changing the customizable fields in our card.
- Replace 'Name' with your name
- Note: Don't change
class="name" - Insert the URL of your Twitter account
href="Insert URL here" - Type your handle in the text field
- If you prefer to use a contact other than Twitter you will need to replace the twitter icon
<i class="fa fa-twitter"></i>by going to Font Awesome Icons searching for the right icon and replacing only thefa-twitterpart with the new icon likefa-facebookfor example. Then follow the same steps above.
Tell us something about you
-
Keep it short and sweet. Think about it more like a tweet than a blog post
-
Share with the community 3 links to resources that are useful for web development
-
This can be anything, a video, a talk, a podcast, an article, a reference, or a tool
-
If you are a beginner don't be intimidated by this, share whatever you know even if you think it's basic. You'll be surprised how many people will benefit
-
Link: Insert the link
href="here"replacing the# -
Title: Write a brief description
title="here" -
Name: Write the resource's name in the text field
>here</a> -
Make sure you have saved all your changes.
-
Test your changes. THIS IS IMPORTANT! Open the html file in your browser (by double clicking on it for example) and see what your card will look like on the site. See that the entire page still looks the same and nothing is broken. Click your links and make sure they are working. Open the console (Ctrl + Shift + J (Windows / Linux) or Cmd + Opt + J (Mac)) and check that there are no error messages.
-
Great, you have finished editing your code! The next steps will send your changes to GitHub and then submit them to be merged with the main project.
- Now open the terminal in your project directory and run
git statusand you'll notice that there are no changes made in git. - You can add those changes you made using the
git-addcommand
git add index.html- Now commit those changes using the
git commitcommand
git commit -m "Add $Username card info"- Replacing
$Usernamewith your Github Username.
- Now that youve commited your changes, they are only saved locally in your local computer.
- Synchronizing local changes with your repository on GitHub is called a
Push. You are "pushing" the changes from your local repository to the remote repository on GitHub. - We use the
git pushcommand to push changes to github.
git push -u origin $Username-card-
Replacing
$Username-cardwith your branch name. -
After a few seconds the operation is complete and now you have exactly the same copy of this branch on your machine as well as on GitHub.
-
This is the moment you have been waiting for; submitting a Pull Request (PR).
-
So far all the work you have done has been on the fork of the project, which as you remember resides on your own account of GitHub.
-
Now it's time to send your changes to the main project to be merged with it.
-
This is called a Pull Request because you are asking the original project maintainer to "pull" your changes into their project.
-
Go to the main page of your fork on GitHub (it will have the fork icon and your own user name at the top).
-
Towards the top of the repo you will see a highlighted pull request message with a green button.
- Click on the
Compare and pull request - This is what the
Open a pull requestpage looks like. - REMEMBER you are trying to merge your branch with the original project not with the
Masterbranch on your fork. - The image below gives you an idea of how the header of your pull request should look like.
- On the left is the original project, followed by the master branch. On the right is your fork and the branch you created.
- Don't be fazed by all the options. You only need to do these three steps for now.
- Leave the option
Allow edits from maintainersticked. - Now, a Pull Request will be sent to the project maintainer. As soon as it is reviewed and accepted your changes will appear on the project web page.
That's it. You have done it! You have now contributed to open source on GitHub.
You have added code to a live web page: https://syknapse.github.io/Contribute-To-This-Project
Your changes won't be visible immediately; first they have to be reviewed, accepted, and merged by the project maintainer. Once they are merged your card should be visible and live on the page.
It is very normal for a reviewer to ask for changes on a PR. Think of it as good practice if it happens to you. Keep an eye for comments and requested changes. Once you make the requested changes (back in your branch) all you have to do is to commit and push your changes. The PR will automatically update with the new changes.
We promise we will try to review and merge as soon as possible but we do this in our spare time, so a few days delay is inevitable.
- Come back in a while to check for your merged Pull Request.
- You should receive an email from GitHub when your changes have been approved, or if additional changes are requested. And when the PR is finally merged with the master and your card has been added.
- If you found this project useful please give it a ⭐ star ⭐ at the top of the page and Tweet about it to help spread the word
- You can follow me and get in touch on Twitter or using any of these other options
- This is an open source project so apart from contributing your card you are welcome to help fix bugs, improvements, or new features. Open an issue or send a new pull request
- To help improve our community take a look at the GitHub Discussions tab located next to Pull Requests. This area is a place to introduce yourself, go into deeper discussions on Open Source, and communicate with the Project Maintainers. Will you help us build out this feature and enhance our community?
- Thanks for contributing to this project. Now you can go ahead and try contributing to other projects; look for the
label for beginner-friendly contribution options. - I'm also looking for collaborators to give me a hand in reviewing and merging PRs. If you would like to get more advanced Git practice please send me a DM on Twitter and read the maintainer's guide.
This project is heavily influenced by Roshan Jossey's great first-contributions project with its excellent tutorial.
It is also particularly inspired by the great community around #GoogleUdacityScholars The Google Challenge Scholarship: Front-End Web Dev, class of 2017 Europe.