Understand GitHub and Install GitHub for Desktop

The first and probably most important thing to do while setting up your open source development environment is to understand how GitHub works. GitHub is a website that allows users the ability to store, track, and create code together using a core version control technology called Git.

What you want to do is to actually store your application on GitHub itself and use gh-pages to describe the project. These gh-pages should have an area that refers to and links to open issues on the project itself.

Tutorial: Install Github for Desktop

To start, go to http://www.github.com/

Create a Username and Password and choose the “unlimited public repositories for free” option.

Click on “Start a Project” and then verify your email.

After verification, create a (public) repository. Make sure to check the “Initialize this repository with a README” and add an open source license using the drop-down menu (Apache or MIT license). This is standard for open source projects.

A repository is a public location that houses all the files for your specific project. Each repository can be cloned so other users can work on it independently and then push edits back to your master branch. You can give the repository any name you choose, but it makes sense to name it after your project.

Next, click on “Setup on Desktop

Next, you should be led to download GitHub for Desktop

GitHub for Desktop is a graphic user interface application that allows you to push changes to GitHub without having to learn how to use your computer’s command line. It’s an easy way to use GitHub – especially if you aren’t familiar with the command line.

Once you’ve downloaded GitHub for Desktop, you should be able to clone the repository to your personal computer’s desktop. Any changes you make to the files inside this repository can be pushed back up to the master branch of the repository on GitHub.com itself. Branches allow users to create alternative versions of files or applications.

Using the GitHub for Desktop tool, you’ll want to get familiar with how to push and pull code from the master branch using the “Sync” and “Commit to master” buttons on the application. Once you understand the basics of how GitHub works, you can help you organization track technical changes by accepting basic GitHub requests.

You can learn more about GitHub here: https://guides.github.com/activities/hello-world/


Tutorial: Create your first gh-pages template

GitHub Screenshot

GitHub has created an easy way to include instructional web pages with your project. This is called the gh-pages.

You can create gh-page by clicking on the “Settings” tab in your repository. Once there, scroll down and click on the “Launch automatic page generator” button and follow the instructions to create a generic project page.

We prefer the theme called “Cayman”, but you can choose any theme you desire.

After hitting “Publish Page”, you’ll be taken to the repo and be able to see the files that have been made for your gh-page. To actually view the page, go to the Settings tab again and you’ll see “Your site is published at https://codeallianceorg.github.io/repositoryName/”. Click on the link and you’ll be able to view the page.

Next, you’ll want to replace the code in the index.html with a descriptive template that helps guide volunteers through the project description, tasks, and open tickets. We’ve provided an example that you can copy and update below. It can also be helpful to include images. In the issues area, you can provide the title of each open issue for the project and link directly from this page.

https://codeallianceorg.github.io/Green-Impact-Campaign/

Green Impact Campaign Template on GitHub


You can copy and paste the template code found here:

<!DOCTYPE html> <html lang="en-us"> <head> <meta charset="UTF-8"> <title>Green Impact Campaign by CodeAllianceOrg</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" type="text/css" href="stylesheets/normalize.css" media="screen"> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700' rel='stylesheet' type='text/css'> <link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen"> <link rel="stylesheet" type="text/css" href="stylesheets/github-light.css" media="screen"> </head> <body> <section class="page-header"> <h1 class="project-name">Green Impact Campaign</h1> <h2 class="project-tagline">Environmental</h2> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign" class="btn">View on GitHub</a> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign/zipball/master" class="btn">Download .zip</a> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign/tarball/master" class="btn">Download .tar.gz</a> </section> <section class="main-content"> <h3><a id="organization-name" class="anchor" href="#organization-name" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Organization Name:</h3> <p>Green Impact Campaign</p> <p><a href="http://greenimpactcampaign.org/">http://greenimpactcampaign.org/</a></p> <p><img src="https://raw.githubusercontent.com/CodeAllianceOrg/GreenImpactCampaign/gh-pages/green3.jpg" alt="Green Impact Campaign" /></p> <h3><a id="project-name" class="anchor" href="#project-name" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Project Name:</h3> <p><b>Map API & GEMS UX Redesign</b></p> <h3><a id="description" class="anchor" href="#description" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Description:</h3> <p>We provide training and tools to volunteers to conduct free energy assessments for local, small businesses across the country. Businesses sign up through our website (Wordpress) that then creates an account for them in our energy assessment tool (Drupal) called GEMS.</p> <p>We want to create a map API on our website (Wordpress) that would show a map of all of the businesses that have participated in our program across the US. We use Formidable for the register forms. We’re hoping that once a business goes through our form, we can extract the data and create a point on a map that shows the business information, like a map directory. Ideally, this happens in real-time. Additionally, we have begun the process of trying to have better UX for businesses and students using GEMS. We would like to have some redesign the tool’s workflow to better serve both users. </p> <h3><a id="looking-for" class="anchor" href="#looking-for" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Looking For:</h3> <p><ul> <li>UX Designers/Developers</li> <li>Wordpress developers / Drupal developers / Scripting</li> <li>Devs for PHP Google maps API</li> </ul> </p> <h3> <a id="open-issues" class="anchor" href="#open-issues" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Open Issues</h3> <p><b>Issues 1:</b> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign/issues/3">Open</a></p> <p><b>Issues 2:</b> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign/issues/3">Open</a></p> <p><b>Issues 3:</b> <a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign/issues/3">Open</a></p> <h3><a id="important-links" class="anchor" href="#important-links" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Important Links:</h3> <p><a href="http://gems.greenimpactcampaign.org/ ">http://gems.greenimpactcampaign.org/</a></p> <h3><a id="contact" class="anchor" href="#contact" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Contact for Questions:</h3> <p>deepd@benetech.org</p> <footer class="site-footer"> <span class="site-footer-owner"><a href="https://github.com/CodeAllianceOrg/GreenImpactCampaign">Greenimpactcampaign</a> is maintained by <a href="https://github.com/CodeAllianceOrg">CodeAllianceOrg</a>.</span> <span class="site-footer-credits">This page was generated by <a href="https://pages.github.com">GitHub Pages</a> using the <a href="https://github.com/jasonlong/cayman-theme">Cayman theme</a> by <a href="https://twitter.com/jasonlong">Jason Long</a>.</span> </footer> </section> </body> </html>

Next Step: