New Contributor Guide to Git
Of course everyone wants to help out, that's why you're here.
Here's how it goes here:
- Contribute to Why Not Earth
- ?????
- Profit
*profit can include but not limited to: happiness, ice cream, better resume, unwarranted attention for your great work, etc. You won't know. We don't know. Why don't you contribute and find out? ;)
This guide is to help people understand how to use git so they can help us create wonderful things. Don't ask Chris. You'll just get really fucking confused.
Here at Why Not Earth we have many projects going on at once. So, we use Github to manage our code and our project progress. Look. Shinta Mani Wild has its own project management board, right here.
All of these little cards are issues, or tasks that need to be completed. Here's an issue you can take a look at as an example.
The whole process kinda goes like this:
- Our design department (ME) writes out new feature or design related issues to add to the to-do list.
- Developers and contributors complete tasks from the project board.
- Our project management team (ME) review and approve changes for developers to merge to staging.
- Our QA department (ALSO ME) finds bugs on our site and add bug issues to the bug list.
- Developers and contributors SQUASH these pesky little bugs so we have a beautiful site.
So you've noticed an issue you can help out with in one of our projects.
Great! We love you.
To get started, you only need a few simple ingredients:
- A working computer with command line / terminal / CMD.
- A Github account (or else how will we know you did amazing work?!)
- A text editor (Sublime, Visual Code Studio, Bracket, Vim, whatever you like)
Git is a system to version control a project. You install the Git client locally and use the Git commands to pull from a Git repository, which for us, is hosted on GitHub, which also provides a GUI for reviewing code, tracking bugs, and managing projects.
To get a GitHub account, go to here and create a free account.
A command line, also called terminal, is basically an interface that allows you to move around and do things on your computer without your mouse.
You can open files, you can download things, whatever. Here's the thing. I'm not an expert. I know how to get from one place to another and do git things. I'm sure it does a hell of a lot more. Meh.
In this guide we use command line as an intermediate between your computer and git.
If you're helping on a project, make sure that you've navigated to your local repo (should just be a file in your computer), or you won't be able to access your files or start a local server.
Mac Terminal Cheat Sheet
Linux Cheat Sheet
Windows/UNIX Cheat Sheet
To use Git, you have to download it on your computer first. Download Git here. Just follow the instructions to install it on your computer.
If you are using a Macbook, your terminal might already have Git installed.
Check that your git is successfully installed by running this in command line:
git --version
If git is fully installed, it will show you which version it is:
git version 2.9.2
Next, configure your username and email for git. Use the email you used for your GitHub account.
git config --global user.name "bamboochow"
git config --global user.email "[email protected]"
Before you start making changes, assign yourself to the issue you're looking at so everyone knows you're in charge of this issue. Issues with no one assigned in the to-do are open for you to contribute to.
Now, you can get your own repo of this project and get started!
A repository/repo is basically a folder that has EVERYTHING related to a single project. Shinta Mani Wild has its own. Why Not Earth Website has its own. Bensley.com has its own. A repo contains the documentation, the code, and the revision history of these projects.
There are 3 repo versions that you'll need to know about.
- Why Not Earth repo: This is the project folder you want your changes to end up in. It's an example of a remote repo because it's stored in a server that your Git client connects to.
- Your own fork of the Why Not Earth repo: This is your own copy of all thes files in the repo so you can work without messing up other people's code. This is also a remote repo.
- Your local repo: This is a copy of your fork that downloads all the file so it's stored in your own computer. With a local repo, you can make changes and play around with the code.
So the flow for these repos work like this:
- Make changes on your local repo in your computer
- Push changes to your fork on Github for review.
- A lead developer will approve your changes and merge them from your fork to the main Why Not Earth repo.
To work on a project, you need your own copy of this folder first. Your own repo, if you're fancy.
Navigate to the project repo you want. This one is Shinta Mani Wild. Its normal link is:
https://github.com/whynotearth/shinta-mani-wild
On the upper right hand corner there's a "Fork" button. Click that, and you'll have a copy ready for you in the form of a url. If I did it myself, it would be:
https://github.com/bamboochow/shinta-mani-wild.git
You have to clone it to create a local copy. Open up terminal/command line/cmd, whatever you call it, and grab the link with your user name in it. Run this command:
git clone https://github.com/bamboochow/shinta-mani-wild.git
This will give you a local copy of the code. Git knows this fork as origin.
Wow. Your very own copy. You did it.
Next up, if you're not already in the folder, navigate in terminal/command line to your local repo. Depending on where you put it, it should be somewhere in your local user files.
Each of our projects include some dependencies that you have to download in order for you to help with the project. Some of them are different, depending on which project we're working on. Make sure you check the README file when you're starting to help out on a project, because we have it in there for each project.
For example, Shinta Mani Wild has this setup in the README:
So, in your terminal, first run this to install all the necessary files:
yarn install
Then to run a local server, run:
yarn run serve
Which will give you a link that you can use in a browser to test locally.
The Why Not Earth repo does the same thing, but has a different set of dependancies:
Github uses branches to manage all those changes that are happening from difference sources. These branches helps you version control your project by separating into different work spaces for different purposes.
The default, central branch of every project is called the master branch. Ultimately, all the code for features that needs to be in the project is going to end up in the master branch. However, we can't have someone make a mistake that completely DESTROYS the master code, no no no no no.
To make sure that doesn't happen, we create our own branches to make individual changes for individual features. Then, you merge these branches into another branch.
What happens during a merge? The changes you've made to your local files in one branch are updated into the branch you want to add things to. We merge our changes into a staging branch, where changes are tested before our developers merge the staging into the master branch where all the good code is safe and sound. You as a contributor don't get to make changes to the master branch. Sorry.
You create branches by making a copy of the master branch. So, if you want to create a new branch called change-name:
git checkout -b change-name master
When you want to switch to another branch you've already made, let's say, delete-image, run:
git checkout delete-image
To see a list of all the branches you currently have running or are currently in, run:
git branch
It should look something like this:
Now, change-name, the branch you just created, exists, but only in your local repository. So at this point, Github (and the rest of the team) doesn't know this branch exists. Later on, you'll need to push this branch so other people can see that you're doing great work.
For our projects, we use an "x-y-z" naming scheme for our branches. X is the issue number, Y is the action (add, fix, hotfix, change, remove, security), and Z is the subject. For example: 224-fix-scrollbar-in-iphone would be an AMAZING branch name. Do that.
Right now on your computer you have a local repository, which is just a copy of Why Not Earth's repository. Since we also have tons of other contributors, your local repo might be outdated already.
So, right before you make any file changes, you're going have to pull the latest changes from Why Not Earth's repo to update your own local repo.
For Why Not Earth generally, we pull from staging. So, you'd move yourself into the staging branch by running this:
git checkout staging
Then, get the latest changes by pulling. To get the latest changes from Why Not Earth's repo, you run:
git pull
If there are changes in your local repo that aren't updated, you'll see what has been changes as an output.
If it's all updated, you'll see this:
Now, your local staging branch has the latest and greatest, but what about your other local branches? What about change-name??? To update your local branch, go to that branch first. For example purposes in this guide, it's change-name :
git checkout change-name
Then merge it to bring in the latest changes:
git merge staging
Here, you'll be able to see if any of your changes are conflicting with someone else's changes on the same file, and you'll be able to resolve that here.
Choose your favorite text editor and make the changes you need for the issue you're working on. Sublime. Vim. Visual Studio Code. Use your favorite. I don't care.
If you use Visual Studio Code, install Vetur, stylelint, prettier and eslint extensions.
Before anything, let's make sure you're hanging on to the right branch, our good old friend change-name.
git checkout change-name
As you're making your changes, keep in mind to maintain the style of coding, naming system, spacings, and other little coding things.
Make sure you save the file. Save it. Save it.
Save.
It.
You've made some fine changes to the code. Good job, you 1337 h4x0r, you.
Now at this point, no one knows about the changes you've made. We've gotta send your masterpiece to the interwebs to be appreciated. To do that, we first label and highlight the changes you made through a commit. After you've finished editing your files in your text editor, save it and run this in terminal:
git status
You'll see an output with a section that says:
Changes not staged for commit
It'll show a list of files you've modified, with some possible next steps you can take. One of these files we're gonna call "youdidstuff.css". This is Git going: "Uh. You changed some stuff. Idk what yb ou want to do with it but you changed some stuff."
So, what you want to do is first stage the files you've changed. So, to stage youdidstuff.css, run this:
git add youdidstuff.css
Do the same for any other files you've changed, just change youdidstuff.css to the name of the file you want to add.
Once you've confirmed that you've added all your files, run your commit with a brief description of what the changes made are about after the -m:
git commit -m "I did some stuff, and now they need to be added."
This will bookmark all these changes together as one action to keep a record of what change you made, and for what reasons.
You need to make sure that your code changes actually work before you add any of your changes into the main repo. To do that, you need to test your code.
Since you already started a local server earlier, all you have to do is save your code, and then refresh that browser window to see your changes.
If you've accidentally closed that window, or if you've stopped working for a bit and picked it back up, you can always run:
yarn run serve
again so your local server starts up again. Remember to navigate to your local repo folder first in terminal before you try to run the local server!
So far you've only been doing everything on your branch in your local repo. Pushing your branch into your Github fork turns your edits into reality. Without doing this step you won't be able to make a pull request and your changes won't happen.
Let's first make sure we have the latest changes from main repo by running these:
git checkout staging
git pull
git checkout change-name
git merge staging
Now, if this is your first time pushing this branch, you can push your changes to origin with this command. Remember, origin is Git's default name of your fork. We're using change-name as our example branch again here:
git push -u origin change-name
This command designates where to push to while pushing into your fork. For any pushes on the same branch in the future, git already knows where to push to, so just run:
git push
Now, other people can see the changes you've made on your own fork on GitHub.
A pull request is a request to have your code reviewed by a developer on the team. Once they've checked that your code is spotless, they'll merge your code with the Why Not Earth repository and your changes will be forever memorialized in a Why Not Earth project.
You can go to the project's repository on github and click "New Pull Request"
Then, you can choose which branches you want to pull to and from. The base is the branch you want to compare to to prepare for merging. Instead of merging directly into master, we usually merge to staging, where we test and play around with our features until things get serious. Then, our developers make it official by merging everything on to master.
Compare the two branches: staging and the branch you've been working from, let's say its change-name. If Github says there are no conflicts and you can merge it, then give your pull request a descriptive title and in detail comment what changes you made to your files, as well as linking the issue you were working on (usually it's something like #143). I guess you can also talk about your day.
Something like this. Maybe more detailed. Who the hell wrote this???
...
Me. It was me. Don't be like me.
Here's a better one.
When you're done, just click "Create Pull Request", and you can even request your favorite developer to review your changes. Once you've made the pull request, all you have to do is wait for it to get approved!
We don't like reusing branches. It makes me really confused and I don't like it. So, once you're done with your changes for your specific issue, make sure you delete the branch you created.
"Well," you ask, "What if I want to make similar changes? Can't I just use that branch again?"
No. Make a new goddamn branch, you heathen. It's free.
Moving on.
You can delete your branch directly on the "Delete Branch" button within Github.
Please don't delete the wrong one. I'll cry. Our developers will cry. In general, at this step, don't touch staging, don't touch master.
Or, you can go to your command line and delete change-name in your fork by running:
git checkout staging
git branch -D change-name
git push -d origin change-name
Goodbye, change-name. Goodbye.
Here's an example of me deleting a branch I misspelled.
You're officially done! Go look at your contribution and celebrate as you like. Chocolates, beer, champagne, puppies, the works. I usually take some time to pointlessly refresh the page and relish the fact that I did something useful. Happiest time of my life. Try it.
Go get your cookie reward from Chris. Then go back to the project and look for more issues to help with. We've got tons of work <3