GitHub For Dummies book cover

GitHub For Dummies

By: Sarah Guthals and Phil Haack Published: 05-29-2019

Code collaboratively with GitHub

Once you’ve learned the basics of coding the next step is to start sharing your expertise, learning from other coding pros, or working as a collaborative member of development teams. GitHub is the go-to community for facilitating coding collaboration, and GitHub For Dummies is the next step on your journey as a developer.

Written by a GitHub engineer, this book is packed with insight on how GitHub works and how you can use it to become a more effective, efficient, and valuable member of any collaborative programming team.

  • Store and share your work online with GitHub
  • Collaborate with others on your team or across the international coding community
  • Embrace open-source values and processes
  • Establish yourself as a valuable member of the GitHub community

From setting up GitHub on your desktop and launching your first project to cloning repositories, finding useful apps on the marketplace, and improving workflow, GitHub For Dummies covers the essentials the novice programmer needs to enhance collaboration and teamwork with this industry-standard tool.

Articles From GitHub For Dummies

page 1
page 2
11 results
11 results
GitHub For Dummies Cheat Sheet

Cheat Sheet / Updated 02-23-2022

When you first log in to GitHub.com, it can feel overwhelming. What is GitHub? GitHub is more than a place to store your code; it’s a community and a philosophy about how code should be written. When you’re first learning and navigating the website, you should always remember that the goal of GitHub is to provide a secure, collaborative environment where newcomers and experts alike can design, develop, and deploy any software, from programs that say “Hello World” to code that sequences human proteins to help cure major infectious diseases around the world. To be a part of this community, you just have to be an effective communicator, find and create collaborative projects, and know how to find the help you need, when you need it.

View Cheat Sheet
Take Action with GitHub Actions

Article / Updated 10-04-2019

GitHub has a feature that removes the need to host our app outside of GitHub, which can reduce the number of moving parts when extending GitHub. This feature is called GitHub Actions. GitHub Actions is one of the newer, most exciting features of GitHub. At the time of writing, it's still a beta feature. GitHub Actions makes it possible to create custom workflows on GitHub. It lets you implement custom logic to respond to events on GitHub. In the previous section, we wrote a GitHub app to do that. With GitHub Actions, we don’t need to build a custom app. We can build workflows using existing actions that others have written, or we can write our own actions that run in a Docker container. Hopefully, by the time you read this, GitHub Actions are generally available. But in the case they’re still in beta, email [email protected] and ask to be in the GitHub Actions beta program. To demonstrate GitHub Actions, consider the following scenario. When you merge a pull request in your own repository, the branch for the pull request sticks around. GitHub presents a button to delete the branch, but a lot of people forget to do so and leave these branches sticking around. Not deleting the branch isn’t necessarily a bad thing, unless you’re the type of person that likes things to be tidy and cannot stand having a branch that’s no longer needed lingering around. If you are that type of person, you’re in luck. Jesse Frazelle is also that type of person, and she wrote a GitHub Action you can use in your own workflows. Her blog post, “The Life of a GitHub Action” is a good read to understand more details about the life cycle of a GitHub action. Creating a GitHub action workflow If you’ve been accepted in the GitHub Actions beta program or it has become more widely available, you should see an extra tab at the top labeled Actions when you view a repository. The following steps walk through the process for creating a GitHub action workflow for a repository. Click the Actions tab to see your existing workflows. If you don’t have any workflows yet, you see a big green button to Create a new workflow, as shown. Click the Create a new workflow button to bring up the workflow designer view. This visual designer lets you create workflows and connect them to actions. Workflows are stored in a file named main.workflow in the .github directory of your repository. There's also an editor view if you prefer to build your workflows with text. Switch to the text editor and paste in the following text: workflow "on pull request merge, delete the branch" { on = "pull_request" resolves = ["branch cleanup"] } action "branch cleanup" { uses = "jessfraz/[email protected]" secrets = ["GITHUB_TOKEN"] } If you switch back to the visual designer, it should look something like the following figure. Click the Start commit button to commit this new main.workflow file to your repository. Testing a GitHub Action After you commit this file to your repository, the workflow is active. You can test it by creating a new pull request and then merging it. A few seconds or minutes later, you should see that the pull request branch was deleted. An update on the pull request says something like github-actions bot deleted the branch-name branch 1 minute ago You can create pretty useful and complex workflows using existing actions. You can install actions from the GitHub Marketplace or reference them by pointing to a repository that contains an action. You can also write custom actions. How to do that is beyond the scope of this article, but you can look at the action that Jesse wrote to get an idea of what it takes. With GitHub Actions, you can personalize GitHub to your tastes in nearly unlimited ways.

View Article
GitHub Apps and Probot

Article / Updated 10-04-2019

Apps on GitHub let you extend GitHub in powerful ways. GitHub apps are web applications that can respond to events on GitHub. These event subscriptions are called web hooks. When an event occurs on GitHub that the app is interested in, GitHub makes an HTTP request to the app with information about the event. The app can then respond to that event in some manner, often resulting in a call back to GitHub via the GitHub API. Here, you walk through building a simple GitHub App that brings a bit of levity to your issue discussions. There’s an old meme in the form of an animated gif with a little girl who asks the question, “Why don’t we have both?” The typical application of this meme is in response to a question that presents a false dichotomy. In other words, when someone presents a question with two choices, someone might respond with this image. Introducing GitHub's Probot GitHub apps are web applications that need to listen to HTTP requests. You have a lot of important details to get just right when building an HTTP request, such as what is the format of the data posted to the app? All these details can be confusing and time consuming to get correct when building a GitHub app from scratch. Knowing where to start is difficult. GitHub’s Probot framework comes in handy when getting started with a GitHub app. Probot handles much of the boilerplate and nitpicky details of building a GitHub app. It is a framework for building GitHub apps using Node.js. It provides many convenience methods for listening to GitHub events and for calling into the GitHub API. Probot makes it easy to build a GitHub app, but it doesn’t solve the problem of where to host the app. Hosting the GitHub app A GitHub app can take many forms. It could be a Node.js app running in Heroku, an ASP.NET Core app running in Azure, a Django app running in Google Cloud — it doesn’t matter. It just needs to be persistent and available via the public Internet so that GitHub can reach it with event payloads. Setting all that up can be time consuming, so for our purposes, we use Glitch to implement a quick and dirty GitHub app. Introducing Glitch Glitch is a hosting platform for web applications that removes a lot of the friction with getting a web app up and running. Any app you create in Glitch is live on the web from the beginning. You don’t have to think about how you plan to deploy the code because any change you make is auto saved and automatically deployed. Glitch focuses on the community aspect of building apps. Every file can be edited by multiple people in real-time, in the same way you might edit a document in Google Docs. And every project can be remixed by clicking a button. This encourages a lot of sharing of code and learning from each other, which comes in handy when we build our own GitHub app. Before you continue, make sure to create an account on Glitch if you don’t have one already. Create a Probot Glitch app After you have a rough understanding of Probot and have a Glitch account set up, you can build a Probot app on Glitch. Glitch lets you remix existing apps, and the good news is Glitch already has a Probot app that you can remix. This means you can create your Probot app with one click and a few customizations. To create your app, type the following URL into your browser: https://glitch.com/edit/#!/remix/probot-hello-world. This command creates a brand new app in Glitch based on the probot-hello-world example with a randomly generated URL, as shown. As you can see, my app is called candy-chaffeur. The left pane shows the list of files in your application. The README.md file contains step-by-step instructions to set up the hello-world Probot app. Follow these instructions carefully to set up the sample GitHub app. One of the instructions mentions running the following command: cat my-app-name.2018-06-20.private-key.pem | pbcopy The purpose of the previous command is to copy the contents of your private key file into the clipboard so that you can paste it into the Glitch file. However, this command works only on a Mac. On Windows, you would run the following command (changing the file name to match yours): type my-app-name.2018-06-20.private-key.pem | clip When you are done, install the app on a repository that you own and then create a new issue. A few seconds later, you should see a comment created by your bot with the words “Hello World!”. Customize the app After you create a Probot app in Glitch and install it on GitHub, you can customize how the app responds to issue comments. When you followed the steps in the README, you subscribed to issue events. These events do not include when new comments are created. We need to also subscribe to issue comments. See a list of your apps here. Click the Edit button to navigate to your app. Then in the left navigation, click Permissions & events and scroll down to the Subscribe to events section. Check the Issue comment check box, as shown. Click the Save changes button at the bottom to complete these changes. Now you need to change your Glitch app to listen to new issue comments and respond appropriately. Edit the index.js file and replace the contents of the file with the following code: module.exports = (app) => { // Listens to new issue comments app.on('issue_comment.created', async context => { // Retrieves the comment text const message = context.payload.comment.body if (message.indexOf(' or ') > -1) { const params = context.issue({ body: '![The why not both girl](https://media3.giphy.com/media/3o85xIO33l7RlmLR4I/giphy.gif)' }) // Creates a comment with a markdown image return context.github.issues.createComment(params) } }) } This code listens to new issue comments, looks for the word or surrounded by spaces, and if it finds it, creates a new comment with a markdown image. This approach is not very smart. Try this slightly better approach. It would be even better if we could employ some artificial intelligence (AI) in the form of natural language processing (NLP). But that's beyond my skillset and out of the scope for this book. Installing the app After you create the app and get it working, others can install the app and use it. You can install it by going to your GitHub apps list and clicking the big green Install button in the top right. Install it on a repository and then go create a comment on an issue in the repository that asks a question with the word or in it. An example interaction is shown here.

View Article
Hackathons and Other Networking Events for GitHub Software Developers

Article / Updated 10-04-2019

GitHub hosts and sponsors several conferences throughout the year. Many kinds of events focus on software developers. They range from the informal meet-up or user group to the structured multiday international software conference. See which GitHub events are upcoming. This page lists GitHub’s own upcoming events, as well as events that it sponsors. Meet-ups and user groups for software developers A meet-up or user group is an informal gathering of developers to cover a topic. Many are scheduled monthly and hosted by a local company or software interest group. These events tend to be a great way to dip your toe into software developer events. They tend to be small gatherings of people in your area. Each month features a local speaker who talks about a topic relevant to the group. (Some user groups and meet-ups bring in speakers from outside on occasion, but typically they focus on highlighting local speakers.) Meetups.com is a great way to find a meet-up relevant to your interests. You can search for meet-ups by location on meetups.com. For example, check JavaScript meet-ups for the Seattle Washington area. A few examples of local meet-ups include Brooklyn JS: Brooklyn, New York .NET São Paulo: São Paulo, Brazil SD Ruby: San Diego, California Regional conferences for software developers A regional conference is a relatively small conference where speakers and attendees outside of the local area are welcome, but the focus of the conference is to provide a venue for local developers and speakers to connect and present their work. Often these conferences are one or two days. Many will have a single track of talks, or two at most. They’re a step up in size and structure from a meet-up and typically occur once a year, as opposed to monthly. Some of them often offer workshops either before or after the conference. These workshops usually cost extra, but offer more in-depth training for a specific skillset or technology. For example, you can often find a full-day workshop dedicated to improving your Git skills. If you can afford it and find one that teaches a skill you want to improve, workshops are often worth the investment. Some great examples of local conferences include .NET Fringe: Portland, Oregon JSConf Hawaii: Honolulu, Hawaii GoRuCo: New York, New York Hackathons A hackathon is very different from a conference. While conferences focus more on having speakers teach a topic through a talk, hackathons focus on building. A hackathon is an event that may last several days where groups of people form teams to work together collaboratively write code to solve some sort of problem. The usual format is some sort of problem is presented and teams are tasked with building a solution. The technology stack they may use is often dependent on the focus of a hackathon. For example, a mobile development hackathon will require that attendees build a mobile app to solve the problem. Hackathon is a portmanteau of the words hack and marathon. Many take the marathon aspect to the extreme by having teams work around the clock with very little sleep. Others try to create a balance of working hours and sleeping hours by forcing contestants to leave the workspace. Hackathons are often very inclusive of beginners. For example, SD Hacks is open to any high school or college student in the world who is 18 or older. You don’t always have to have a team when you sign up for a hackathon. Often, you can find one when you get there. It’s best to check out the FAQ for the specific hackathon to learn more about the details. One of the largest, worldwide hackathons is targeted to college students. It’s the Microsoft Imagine Cup. Winners of the Imagine Cup can win mentorship from Satya Nadella (Microsoft CEO), travel to the world championship, and receive Azure grants and $100,000. Attending hackathons can be a great way to be introduced to a new technology. The goal isn’t to design and implement a final product, but rather to hack together bits and pieces to make progress on an idea that you have. The end product should look more like a prototype than a polished application. Often times, hackathons will have mentors that know a particular technology that you can learn from. Think of a hackathon as a dedicated time and place to experiment and learn. Though attending a formal hackathon will provide you with mentors, a space, and sometimes prizes, you can also always get together with friends to do one on your own, too! Just pick a time, place, and goal and try to hack together a prototype of an idea you have! It doesn’t hurt to give it a shot! Major conferences for software developers A major conference tends to be large and draw attendees from all over the country, if not the world. Attendee counts tend to be in the thousands. Attending one of these conferences requires a bit more up-front planning. It’s not just arranging your flight and hotel. These conferences tend to have many tracks, so for any given time slot, you may have to choose which talk you want to see from five or more talks at the same time. Like a regional conference, major conferences often offer an array of workshop offerings before or after the conference. In addition to workshops, many also include hands on labs during the conference. Labs are usually included in the price of the conference and offer a great chance to actually try out the technologies you’re hearing about at the conference. Many of these conferences are thrown by large technology companies, such as Microsoft’s Build conference and Apple’s WWDC. A few examples include Oscon: Portland, Oregon Build: location changes each year WWDC: San Francisco, California GitHub Universe GitHub Universe is the flagship conference for GitHub. It is held yearly in the city where GitHub’s main headquarters resides, San Francisco, California. The conference is usually held in the fall around October or November. As GitHub describes it, GitHub Universe is a conference for the builders, planners, and leaders defining the future of software. This conference is where GitHub typically makes its biggest announcements of the year during the keynotes. It attracts well-known speakers from prominent software companies. In 2018, the conference had around 1,800 attendees who attended three tracks of talks. The cost of the conference is reasonable, around $99 per person, or $199 if you also attend the workshops. GitHub Satellite The GitHub Satellite conferences are an offshoot of GitHub Universe. They bring a GitHub universe-style conference to locations around the world. Held once a year, past Satellites have been held in places such as Berlin, Tokyo, and London. GitHub Constellation GitHub Constellation is a series of small community events held multiple times a year around the world. These events focus on the local community and often feature speakers local to the area. They are typically free and occur over one or two evenings. They’re not all-day conferences like Satellite and Universe. Git Merge Git Merge, is a conference sponsored by GitHub, but focused on the Git version control tool and the people who use it every day. As GitHub puts it, Through technical sessions and hands-on workshops, developers and teams of all experience levels will find new ways to use, build on, and scale Git. The conference features a preconference hands-on day of workshops focused on a range of Git topics. This conference is a great one to learn more about Git and to improve your Git skills.

View Article
The GitHub Marketplace

Article / Updated 10-04-2019

Many tools extend or integrate with GitHub. A good way to find tools to use with GitHub is the GitHub Marketplace. The GitHub Marketplace is a directory of tools and apps grouped in the following categories: Chat Code quality Code review Continuous integration Dependency management Deployment Learning Localization Mobile Monitoring Project management Publishing Recently added Security Support Testing Utilities The Marketplace is a great way to find an app for every situation on GitHub. Purchasing or installing apps through the Marketplace has two key benefits: ease of billing and installation and the vetting process. Billing made easy in the GitHub Marketplace For apps in the GitHub Marketplace that require payment, installing the app through the Marketplace is a streamlined flow because you can use your GitHub payment info. That way, you’re not dealing with five different payment providers when purchasing five different apps to use with GitHub. If you have a free GitHub account, you may not have setup your payment information in GitHub. To set up a payment method, click your avatar in the top right corner of GitHub.com and click Settings. From this page, click Billing from the list on the left side. Here you can click the Add payment method, as shown. The GitHub Marketplace vetting process One of the benefits of installing an application from the Marketplace is that these apps must meet certain requirements before GitHub will list them in the Marketplace. The requirements help ensure a higher standard of quality and security with the apps; helping ensure that these apps are useful (no Fart apps) and are secure. At the moment, a GitHub Action doesn’t require any review to be listed in the GitHub Marketplace, which means installing an action from someone you don’t know may be a bit riskier. An app must meet four main categories of requirements before being listed in the Marketplace: User experience: This brief set of nine requirements includes things like the app must have a certain number of users and installs already. It also includes some requirements around the behavior of the app, such as the app must include links to documentation, it can’t actively persuade users away from GitHub, and it must provide value to customers. Brand and listing: This set of guidelines and recommendations center around the branding of your app and your app’s listing. Every app must include its own logo. If the app makes use of GitHub’s logo, it must follow GitHub’s Logos and Usages guidelines. The brand and listing section on the Requirements page has links to further logo and description guidelines. As you can see, GitHub takes listing apps in the Marketplace seriously. Security: GitHub will conduct a security review of apps before listing them in the marketplace. A separate document with security best practices and more details on the security review is available. Billing flows: Every app in the Marketplace must integrate billing flows using the GitHub Marketplace webhook event. This requirement ensures that people can purchase a subscription to your app and cancel that subscription with the payment info they already have on file with GitHub. It also ensures that any changes made through GitHub are reflected immediately on the app’s own website. How to list your app on the GitHub Marketplace Getting your own app listed in the Marketplace may increase the potential audience for your application. However, listing your app requires that it meets GitHub’s requirements and receives approval. To start the process of listing an app, click the Submit your tool for review link at the bottom of the Marketplace landing page or navigate to the New page of the GitHub Marketplace in your browser. This page lists your applications that you can turn into Marketplace listings, as shown in the following figure. Click Create draft listing next to the app you want to list on the Marketplace to start the process. This takes you to a page where you can enter a name for the listing and choose one of the marketplace categories for your app, as shown. If you save the draft of your listing but happen to close your browser, you can get back to your listing in your browser. After you fill in these details, click Save and add more details to save a draft of your listing and move on to the next set of steps, as shown. These steps include Add your contact info. This info is a set of three email addresses: Technical lead, marketing lead, and finance lead. Fill out your listing description. This area is where you fill out more details, such as a product description, logo, and screenshots. The information here will be displayed on the Marketplace page for your application. Set up plans and pricing. This is where you can set up one or more pricing plans, including the option to create a free plan, a monthly plan, or a monthly per user plan. You can also specify whether a plan includes a 14-day free trial. Set up webhook. This step allows you to specify a URL where Marketplace events will be sent via an HTTP POST request. The webhook will send you information about events, such as purchases, cancellations, and changes like upgrades and downgrades. Accept the Marketplace Developer Agreement. In order to list your app in the marketplace, you have to accept the Marketplace Developer Agreement. Click the Submit for review button. GitHub employees will review your submission to make sure it meets the requirements to be listed in the Marketplace. Consider common apps to install Here are some of the most common and useful GitHub apps that you may want to consider installing. Continuous integration Continuous integration (CI) apps automatically build and test your code every time you push it to GitHub. If you have a CI app, such as AppVeyor, installed on your repository, you will see the status of the check at the bottom of each pull request, as shown. If you’re the owner of the repository, you can also specify whether checks have to pass before the branch can be merged into the master branch. Just head into the Settings tab. If you have any rules on the master branch already, click edit; otherwise, click Add Rule. From there, you can scroll down and select Require status checks to pass before merging. Code quality Code quality apps automatically review your code with style, quality, security, and test-coverages checks. These apps can be really useful for ensuring your code is kept to a high standard. With well-styled and quality code, you’re less likely to introduce or miss bugs. For example, if you require that all curly braces are on new lines and indented with one tab per nested brace, you’re likely to be able to spot when something is incorrect. For example, Rubocop checks the style of your Ruby code while it’s building and provides you with style feedback, such as casing for method names. Another useful type of code quality apps is the code coverage apps, such as Codecov. Shown in the following figure, Codecov and apps like it comment on pull requests with how much of the code is covered by test scenarios, helping to ensure your code remains well tested. Localization Localization apps can make publishing your app in many languages easier. For example, the Crowdin app will link your repository to a Crowdin account where people from around the world can help you translate your documentation and any written words in your software (for example, on buttons or in menus). With more than 20,000 people contributing to translations, the Crowdin app will automatically open a pull request on your repository with new translations when it’s reached a threshold of accuracy, still giving you a chance to review and merge. For open source projects, Crowdin is free! Monitoring Monitoring apps help measure performance, track errors, and track dependencies in your code. For example, Greenkeeper is a real-time notification app that gives you updates and changes for JavaScript dependencies. This figure shows Greenkeeper in action, opening a pull request to update eslint to the latest version. Dependency management Modern app development today is heavily dependent on public package managers for pulling in and managing dependencies. A typical app may have dozens, if not hundreds, of dependencies. Tracking which of these dependencies are up-to-date can be difficult. Github apps like Dependabot check to make sure your dependencies are up-to-date and submit pull requests to update the ones that are not. Sometimes you don’t want all your dependencies on a public package registry. For example, if you work in an enterprise, you may have internal packages that should remain private. A private package registry tool, such as MyGet, is useful in this case. MyGet works with NuGet packages and lets you set up a policy where pushes to a particular branch will initiate a build and the branch will be deployed to a custom NuGet feed hosted on MyGet. Testing Testing software is an important part of the software development lifecycle. Good testers develop test plans to ensure that testers do a good job of testing each release. Managing test plans and keeping track of the status of test runs is an important part of quality assurance. The TestQuality app integrates with GitHub to helping developers and testers create, run, coordinate, and monitor software testing tasks. Learning A great way to learn GitHub is to install the GitHub Learning Lab from the Marketplace. Installing Learning Lab install a bot that walks you through interactive lessons on how to use GitHub through a set of tasks that you complete. The lab is free and lets you take as many courses as you like at your own pace.

View Article
How to Write a Great GitHub Pull Request

Article / Updated 10-04-2019

Writing a great pull request in Git for your GitHub account is a bit of an art. For an open source project, much of the project’s communication with people occurs within pull requests. If you’re contributing to a project, your pull request is your chance to make a strong case for why your code should be pulled into the main branch. Make sure to put your best foot forward. Know the audience for your Git pull request Before you write a single word, understanding your audience is helpful so that you can focus your words on what is most useful. A pull request may serve many audiences. Keeping all of your audiences in mind is important, but your primary focus is on the folks who will review and make a decision on whether your pull request will be merged. You want to make their lives easier as they tend to be very busy. Even though the project maintainers are your primary audience, you should never forget that many others will read the pull request. For an open source project, that audience may be the entire world. So, keep your language respectful, friendly, and inclusive. It’s pretty common to have someone write a pull request in a fit of anger and later regret the words they use. So if you happen to be rage coding, take a moment to cool down and gather your thoughts before creating the pull request. Make the purpose of your GitHub pull request clear Make sure to be concise and informative. For example, the summary should make the purpose of the pull request clear. The summary is the only part shown on the page that lists pull requests. It needs to be scannable. Here are some examples of good pull request summaries: Adds the About page to the website Minimize boilerplate setup code for JavaScript libraries Extract and isolate error handling from GitStore internals Here are some bad examples taken from my own repositories. Teams are forever Typo Small changes The description should provide a bit more explanation about the purpose of the pull request. Don’t write a book, but do make it clear what the pull request attempts to accomplish. Keep your GitHub pull request focused Much like a commit, a pull request should not contain a bunch of unrelated changes. A pull request may consist of multiple commits, but they should all be related to the task at hand. You can often tell that a pull request is doing too much when writing a concise description of what the pull request accomplishes is difficult. Even if the pull request is focused on a single major change, keep the pull request to a manageable size. Reviewing a very large pull request is difficult. If the pull request addresses a very large task, break down the task into smaller steps and submit pull requests for each step. Explain the why behind your GitHub pull request The previous suggestion focuses on what the pull request does. You also need to explain why you’re taking on this work. The pull request description is an opportunity to provide links to other documents that provide more context. You can’t assume everyone will be familiar with the history. If you have a lot of context to share, you can provide a brief summary followed by more details within a tag. For example, if you add a pull request comment with the following text: The reason we're embarking on this work is due to compliance reasons. ## More Details I don't want to bore everyone with all the nitty gritty details, but for those who are interested, keep on reading… GitHub displays the details section collapsed by default, as shown. Click the details label to expand the details section, as shown here. How to add an image to your GitHub pull request GitHub supports adding images to a pull request description by dragging and dropping an image. When you drag and then drop the image on the text field, GitHub uploads the image and replaces it with the markdown for rendering an image. The following figure shows an upload in progress after an image is dragged into a pull request comment field. This comment is very meta as it’s a screenshot of the same repository it’s a comment on. If an image is worth a thousand words, an animated gif is worth even more. If you can create an animated gif that demonstrates the behavior change introduced by the pull request, adding that gif to the pull request is usually very appreciated by those who review it. Include a call to action in your GitHub pull request You need to be very clear about what feedback you want from others on the pull request. For example, if the pull request is a work in progress, make that clear from the start so that people don’t waste time reviewing a pull request that isn’t ready for review. To make that clear, follow the conventions of the repository. You can find out the conventions by orienting yourself with the repository. Following the conventions is important so that others know what is expected of them with respect to your pull request.

View Article
What Are GitHub Pull Requests?

Article / Updated 10-04-2019

The name pull request is confusing to some folks. “What exactly am I requesting to be pulled?” Good question. A pull request in GitHub is a request to the maintainer of a repository to pull in some code. When you write some code that you want to contribute to a repository, you create and submit a pull request. Your code contains some proposed changes to the target repository. A pull request is your way of offering these changes to the maintainer of the repository. It gives the repository maintainers an opportunity to review the changes and either accept them, reject them, or ask for more changes to be made. Pushing code to GitHub To push code to GitHub, you need a repository. Open the repository of your choice. The first thing to do is create a new branch. Creating a new branch before writing new code is standard operating procedure with Git. A pull request doesn’t consist of an arbitrary set of changes or commits. A pull request is always associated with a branch. In other words, a pull request is a request to merge one branch into another. While it’s true that a pull request can target any branch (except itself), the most common scenario is to target the main branch of a repository, typically named master. This relationship between pull requests and branches is why you should create a new branch when starting new work. We name the branch new-work for this example, but feel free to name it whatever you want by replacing new-work with your own branch name in the following command: $ git checkout -b new-work Now that we have a branch, we need to create a commit in that branch. For this example, the specific contents of the commit are not important. You can choose any file and make some edits to the file, such as adding some text to the end. Or manually edit the README.md file manually or run the following command to append some text to end of the file: $ echo "\n## Installation" >> README.md Now that you have a file with some changes, commit those changes. You can use the following command, for example, to commit all your changes. The commit message is not important here. The important thing is to have a commit in a branch to work with that is not in the master branch. $ git add -A $ git commit -m "Add text to the README" Now push this new branch to GitHub.com (replace new-work with your branch name): $ git push -u origin new-work The git push command tells Git to push local commits to a remote repository. The -u flag specifies where to push it — in this case, to a branch also named new-work on the remote named origin. The -u flag is only needed the first time you push a new branch to the server. From that point on, the new-work branch on your local machine is associated with the new-work branch on GitHub.com and any subsequent pushes to that branch do not need the flag. How to open a pull request Before you can open a pull request, your GitHub.com repository must have at least one branch other than the default branch. If you followed the preceding steps, you have a branch that is not yet merged into master. In our case, the branch is named new-work branch, but you may have named yours something else. Visit the repository on GitHub.com to open a pull request. When you visit the repository on GitHub.com, you see a new message in the section labeled Your recently pushed branches, as shown. Click the Compare & pull request button to navigate to the Open a pull request page, as shown in the following figure. The target branch (the branch you want to pull your changes into) is the default branch for the repo. Your branch is listed next to the target branch, and a status of whether your branch can be merged into the target branch is next to that. The pull request title is the same as the most recent commit message — in this example Add text to the README — and your description is blank. The following figure shows an example description. You can change the default branch by choosing Settings→Branches section of your repository. The pull request From the Open a pull request page, you can enter a summary and description. Most of the conventions for commit messages also are supported in a pull request — for example, mentioning people using the @USERNAME format. In the preceding question, I mention @sarah-wecan. When I create the pull request, @sarah-wecan receives a notification. You can reference issues and other pull requests using the #ISSUEID format. And, of course, you can add emojis, such as :sparkles:. In this section, we cover what to write here in more detail. There's a lot that goes into a good pull request. How to add reviewers To the right of the pull request summary and description fields is a set of options for the pull request. The first one, Reviewers, lets you specify one or more people that you want to review your pull request. To add reviewers: Click the gear to see a list of people you can mention. For repositories with a large number of users, you can start typing to filter the set of users. Click each user to add them to the list of reviewers. When you add a reviewer, they’re immediately notified when you finish creating the pull request. The following figure shows the reviewers list with two reviewers selected. How to specify assignees The next option after Reviewers is an option to specify assignees. An assignee is the person who should take action on the pull request. Often, a pull request represents a work in progress and not the final result of some work. If more work needs to be done on a pull request, you’d assign the pull request to the person that should do the work. To specify assignees: Click the gear to see a list of assignees. The assignee dialog box works just like the reviewers dialog box. It allows you to select one or more assignees. Click each user to add them to the list of reviewers. In most cases, it’s best to just assign one person who will be responsible for the next step. Assigning one person reduces the chances that multiple assignees all think the other assignees are responsible for the work. How to specify labels Labels are a way to figure out what to work on next. Labels work the same way for pull requests. They provide convenient grouping and context to help you decide what to work on next or what to review next. The set of labels you can use on issues and pull requests are the same, but some labels make more sense for issues than pull requests and vice versa. For example, many repositories have a “ready for review” label specifically for pull requests. Specify projects and milestones The last two options allow you to specify the project board and milestone that this pull request belongs to. How to create the pull request After you have the pull request written and specified all the pull request options, click the Create pull request button to save all your work and create the pull request. This figure shows a pull request created on my repository.

View Article
How to Set Up a GitHub Repository

Article / Updated 10-04-2019

A GitHub repository is a folder with all the files needed for your project, including the files that track all the versions of your project so that you can revert back if you make a mistake. A repository on GitHub also tracks who can collaborate and how. To get a better understanding of what a repository is and how it is structured, you need to create your first GitHub repo: Go to the home page of GitHub.com by clicking the Octocat. A list of your repositories appears on the bottom left side of the screen. Click the green New Repository button. The Create a New Repository dialog page, shown in the following figure, opens. Type the name of your repository in the Repository name text box. I named my repository HelloWorld. Type a short description in the Description text box. Select the Public radio button. Click the Initialize this repository with a README check box. You do not need to add a .gitignore. Choose a license from the Add a license drop-down list. Click Create Repository. The home page of your repository appears. It should look similar to the one shown in the following figure. Notice that a markdown file — README.md — is already in the repository. Markdown is a lightweight markup language used to style the words that you write with a plain text syntax. You can make words bold, turn them into headers, and even create a table for data. Information at the top of your GitHub repository At the top of the repository is the username of the author and title of the repository. When you fork a repository, you see the original author underneath for a quick link. To fork a repository is to make a copy of it, where the changes you make to your copy can be suggested to the original author. To the right of your username are three buttons: Watch: You can choose what kind of notifications you want to receive based on the type of activity happening on this repo. Star: Starring can help you quickly navigate to certain repositories, as well as give GitHub insight into things you’re interested in so that recommendations will be more accurate for you. To access your starred repositories, just click your avatar on the top right of GitHub.com and choose Your Stars. Fork: If you are not the author of the repository, then you have the option to fork it. We highly recommend choosing either Not watching or Releases only for the majority of repositories so that you only get notifications when you’re specifically mentioned or actively participating in a discussion on an issue or a pull request. Otherwise, your inbox will be filled with emails about every single action taken on the repository, which will get out of hand very quickly. If you notice this happening, go to GitHub.com and unwatch all or some of the repositories you’re watching with a quick click. Tabs on your GitHub repository Seven tabs appear across the top of your repo. Each tab provides different features for the repo: Code: The Code tab is where you can find all your code and browse folders and files. You can click a file to view its contents or click the pencil icon to modify the file, right in your Internet browser. (See the upcoming “Code tab” section for more details.) Issues: Issues are a really neat feature for repos. Issues can help you track things you want to still make, problems you’re having, or suggestions for other people. Pull requests: Pull requests, also referred to as PRs, are similar to issues in that they have a title and a description, but they also have code changes that you’re requesting to be pulled into the main branch. The safest way to contribute code is to create a new branch, make your code changes on that branch, and then request for that branch to be merged with the master branch. A PR gives you an interface for merging the two branches, showing you the diff between the files you modified and the ones that are on the master branch and giving you a place to have a conversation with collaborators on whether the code should be merged or changes should be made first. Projects: You may already be familiar with project boards like Trello or Kanboard. GitHub has project boards linked directly with your repo. The best part is that the cards on a GitHub project board can be directly related to issues or PRs and can automatically move when something happens. Wiki: Wikis are a great place to store documentation, project status, and roadmaps for your project. It’s a great go-to place for collaborators to see what is going on and where they can jump in to help! Insights: The Insights tab, shown in the following figure, gives you an overview of all collaborators and actions happening on the repo. It’s really neat to see this tab on popular open source projects. For example, TensorFlow has had 158 contributors in the last month! Settings: The Settings tab is visible only if you have the right permissions on the repository. In this tab, you can decide who has access to what and how collaborators should collaborate. You can also integrate apps that tell you how much of your code is covered with tests. Code tab of your GitHub repository The Code tab, shown in the following figure, has a lot of additional important metadata about your repo that will come in useful in future development: Description and topics: At the top of the Code tab is a description and a place where you can put in topics to make your repository more discoverable. Adding topics is particularly important if you want to attract other coders to help you build your software. Metadata: This bar contains information and links to the number of commits, branches, releases, and contributors for the repo. Action buttons: On the left side of the repo is a drop-down menu where you can change which branch you’re looking at or browse the files for a particular branch. The New pull request button allows you to quickly create a pull request. The best way to create a pull request is to switch to another branch, make some changes, and then click New pull request. On the right side are three buttons related to files: Create new file, Upload files, and Find file. Finally, you can click on the green Clone or download drop-down list to clone or download the code to your local machine. Code: At the bottom of the Code tab is a list of all the code in this repo. If a md file appears in this list, then the file shows up below the list. For any file, you can click the filename to go to a page where you can see the file and edit it if you want.

View Article
How to Set Up the GitHub Desktop

Article / Updated 10-04-2019

GitHub Desktop is a free, open source application that makes it easier for Mac and Windows users alike to manage repositories and GitHub connections on their local computer. The fact that Desktop is open source means that you can follow the development of new features, connect with the developers right on the actual repository where the application is being built, and even choose to add features you’re interested in having. To install the GitHub Desktop on your computer: Go to GitHub Dekstop and click Download for the platform you’re using. After the download finishes, click the file that was downloaded. The file automatically unzips. On Mac, the GitHub Desktop application appears in your Downloads folder, next to the zip file. On Windows, the application immediately opens after you unzip the file. On Mac, drag the purple GitHub Desktop application into your Applications folder. On Mac, go to your Applications folder and double-click the GitHub Desktop icon. The application opens. You may get an alert that you are trying to open an application that was downloaded from the Internet. Click “Open” if this alert appears. Before you can use GitHub Desktop effectively, you have to do a few things to connect it to your GitHub.com account. If you do not yet have a GitHub.com account, take the time to sign up now. If you already have a GitHub.com account and have already downloaded GitHub Desktop, you can set up GitHub Desktop with the following steps: Open the GitHub Desktop application. Choose File→Preferences. On the Accounts tab, click Sign In on the GitHub.com row. The Sign In dialog box, shown in the following figure, appears. Type your username and password and click the Sign in button or click Sign in using your browser. When you click Sign in, all the dialog boxes close. Repeat Step 1 to re-open the preferences. Your account with your avatar, name, and GitHub username appears under the GitHub.com row, confirming that you have successfully logged in. Click on the Git tab. The information has been auto-filled for you. On the Appearance tab, choose Light or Dark. Set other preferences, such as the Editor and usage data, on the Advanced tab. Select whichever editor you prefer. Agreeing to send usage data is checked by default. By leaving it checked, you help the GitHub Desktop development team understand how all users use the application and therefore make it better. If you do not have a GitHub repository on your computer yet, you can stop the setup here. While a team of folks at GitHub predominately does the development of GitHub Desktop, a part of their role is to support community members who want to contribute to the project. Don’t hesitate to reach out to the team on its repository.

View Article
How to Sign Up for and Personalize a GitHub Account

Article / Updated 10-04-2019

GitHub.com offers unlimited free public and private repositories for individuals. Free private accounts are limited to three collaborators. You can sign up for a paid account to have unlimited collaborators and some Pro features. Sign up for and then personalize the settings on your GitHub.com account. Public means that anyone can see your code, clone your code, and therefore use your code. GitHub is a huge supporter of open source software (OSS) and therefore encourages public, shared code. Open source software is more than just public, shared code. Because every line of code can be traced to an author, you still get credit for what you've written, but the goal is to keep the code available for anyone to use, extend, and explore. How to sign up for a GitHub.com account The following steps guide you through signing up for a free, individual GitHub.com account: Go to GitHub.com and fill out the Sign Up form. Choose the plan you want. For the purpose of this book, you can use the Free plan. You can always upgrade to a paid plan later if you decide you want to have more than three collaborators for your private repository and other pro GitHub features. Complete the brief survey. This survey helps GitHub understand who is using the software and helps them support workflows specific to their users. You’re now at the home page, shown here. How to personalize your GitHub.com account As you become a more experienced coder, you may want to reference your GitHub.com profile on your resume and job applications. More and more companies care more about your portfolio than a list of degrees or awards. For example, GitHub doesn’t require you to provide information on your education as part of the hiring process and instead asks for a link to your GitHub.com profile and/or portfolio. To complete your GitHub.com profile: Click the avatar icon in the top right corner and choose Your Profile. Click Edit Profile on the page that appears. Fill out the form on the Personal Settings page, shown in the following figure. Click Update profile when you’re finished. On the Personal Settings page, you can also adjust a number of different settings to continue personalizing your account. Account In Account settings, you can change your password, change your username, or delete your account. Changing your username may cause unintended side effects, so it typically isn’t recommended. Just make sure that after you change your username that anything that you need to continue working still does. Follow links, test code, and run your applications again. Emails GitHub allows you to link multiple email addresses to your account. Notice that you can add email addresses, keep your email address private, and even block Git commands that may expose your email address. Notifications Notifications can get really overwhelming. Though you can choose your level of granularity for receiving notifications per repository, this page creates your default preferences for notifications. We recommend not automatically watching repositories because any kind of activity that happens on any repository that you interact with will start to show up in your inbox, which turns out to not be helpful as you begin collaborating more. Click the Things you’re watching link at the top of the notifications settings page to check to see what you’re watching and therefore what notifications you may get from them. Billing You can upgrade your plan at any time to include Pro features, such as unlimited collaborators and advanced code review tools. You can make this upgrade happen on the Billing settings page, shown in the following figure. In addition to upgrading your plan, you can also purchase Git LFS data and other Marketplace Apps. You can even put in coupons from your company, school, or affiliated organization. Git LFS stands for Git Large File Storage. Some software development requires large files, such as game scenes in video game development, to be stored. Without Git LFS, you can upload files as large as 100MB. Anything larger requires Git LFS, which supports files up to a couple GB. SSH and GPG keys At some point, you may want to create an SSH or GPG key to encrypt your communication with GitHub and ensure a secure environment. You can do this in your settings, shown here. SSH keys enable you to connect to GitHub from your local machine without having to put in your username and password each time. GPG keys mark tags and commits that you make as verified, meaning that other people know that it was actually you who push the changes. Another way to tell Git to remember your credentials is to use a credential helper. GitHub tends to recommend this over using SSH, especially for Windows users. Security Not only should your password be complex, but you should also consider enabling two-factor authentication. Two-factor authentication means that when you type the correct password, you’re asked to further verify that it is you who is attempting to log in through an app or SMS. Sessions Sessions allows you to see every computer address, city, and country where you’re logged in or connecting to GitHub.com. Blocked users In the Blocked users settings, you can block users from all your repositories. Repositories The Repositories section lists all the repositories that you have created or been invited to as a collaborator. You also can leave repositories from this page. Organizations Organizations enable you to put GitHub users and repositories under similar settings. For example, you can grant admin rights to all repositories in an organization to the entire organization, instead of having to individually add each person to each repository. Read about Organizations on the GitHub Help page. Saved replies Saved replies, shown in the following figure, can be extremely useful for popular OSS. For example, if you’re building an extension to an application, a lot of folks may report problems with the application, not with your extension. You can write a saved reply to point folks to where they can provide feedback on the application when they find an error. Applications You can connect three kinds of applications with your GitHub.com account: Installed GitHub apps: GitHub applications that you are using with your account. One example is GitHub Learning Labs. Authorized GitHub apps: Applications that you have authorized to access your account. One example is Slack. Authorized OAuth apps: Applications that you have authenticated with using GitHub credentials. One example is GitHub Desktop. Developer settings The last section on the Settings page is Developer settings, which you use only if you’re building an application that accesses the GitHub API, which means the application needs to access GitHub data in some way. Three settings appear in this section: OAuth apps: Applications you have registered to use the GitHub API. GitHub apps: Applications that integrate with and extend GitHub. Personal access tokens: Similar to SSH keys, tokens that allow you to access the GitHub API without requiring authentication.

View Article
page 1
page 2