If you have questions, please open an issue and let us know so we can share that knowledge with the world - we guarantee you're not the only one with that question! 😊
This is a reference guide on how to use GitHub for non-technical people.
It is intended for people who will not be adding code to GitHub but want to know how to track a project's progress and will be contributing mainly through issues.
At dwyl, we use GitHub to manage all our projects.
We like to have a 'single version of the truth' where all communication happens in one place (rather than across email, chat systems, a project management tool, GitHub, etc).
Doing this means:
- Everyone knows exactly where to look for any information on the project
- Information is always up to date
- Communications are transparent to the whole team
- Progress is clear to the whole team
- There is a full history/audit which anyone can access
We've created this reference guide to provide people who are not developers (and therefore less used to using GitHub) with the essential information they need to be able to follow the progress of a project, understand what they're seeing and participate in the conversation.
Some sections here are intended to be a walkthrough. Feel free to explore Github while following along with the guide!
- Go to https://github.com and click 'Sign Up' in the top right!
- Enter your username, email address and password to create an account.
- Choose the free tier, which will be selected by default
...and then you'll officially be a Github user!
Next, you'll have to verify your email address, otherwise you will not be allowed to create or comment on issues (which we'll come to later). You should have received an email to verify your email address, but if not, do the following:
- Click on your profile picture in the top-right of the screen:
-
In the left sidebar, click Emails:
-
Next to your email address, click Send verification email. Now you should have an email sitting in your inbox where you can verify your email address!
NOTE: Github often updates, so in this instance you may only have to add a new email under the Emails section and you will automatically receive a verification link.
Let's start busting some of the tech jargon on Github. An organisation represents a group of people working together, like a company or a collaborative project. For example, dwyl!
A repo, which is short for repository, is a directory or storage space for a project. It can be contained in a folder on your computer, or it can be kept on GitHub. You can keep code files, text files, image files or any other type of file inside a repository.
To get onto a repo's page, you can browse an organisation's repos on the organisation page shown above. Alternatively, you can search for them in the search bar which is also shown above and here. Once you've found the repo, click on the title and you'll be taken to the repo's page.
Once you're on the repo page, you can scroll down to find the readme. A readme is a document which should contain a great deal of the information concerning a project: What the project is for, why it is being worked on, who is working on it, how to run the program and how you can contribute, and so on. You're reading this repo's readme right now!
You may be wondering where you can find the code on a repo. There isn't any code on this particular repo, but if you browse through the repos found on the dwyl organisation page, you will find repos which hold a lot of code, like this one:
The code can be found in folders like lib (short for library), public and styles. Files with code in them will typically end with .js for Javascript, .html for HTML and .css for CSS, amongst others.
For some of the terminology you may find while looking at the repo, have a look at our terminology section.
Issues are how a team will track their tasks for the current sprint (a single iteration of the project, see here), store ideas for future features and log any bugs that they find which need fixing.
To access a project's issues, click the Issues tab which is shown immediately below the repository name:
By default you will now see a list of the repo's open issues. When you create an issue, it is treated as open, and is only closed when the team or individual who created the issue feel it has been adequately addressed.
When looking at the list of open issues, you will be able to see the titles of the issues, who opened them, when they opened them, who is assigned to them, as well as what labels are attached to the issue. Labels are a handy way of organising groups of issues and identifying the subject and content of an issue - e.g. question or enhancement.
To create a new issue, click on the New issue button on the top right of the Issues page
Here you'll be able to specify details about an issue, give the issue a label, and assign the issue to a project collaborator (or yourself!).
If you click on an existing issue, you can expect to see comments from various collaborators, references to other issues, as well as references to previous commits and pull-requests (see terminology section!). Everything within an issue is tracked in real-time, and you can add and remove labels, which we mentioned above.
Within an issue, as we mentioned above, it is possible to reference other issues. When viewing a list of issues, you will see the issue number alongside a hashtag (#), immediately underneath the issue title:
When you're within an issue, the issue number can be seen next to or under the title of the issue.
So, you can cite this issue number within an issue to reference another issue, like so!
This issue will appear in the other one:
Additionally, you can mention someone in an issue comment, by typing an at-sign (@), followed by their Github username, to notify them, as shown here:
We love using Github issues for project management, and we're conscious the above is a lot to take in, so perhaps this video will help clarify the issues interface, and help to visualise what is going on within the issues section, and why it can be so useful.
NOTE: This is a slightly old video so the User Interface is not the same as the current one. Most of the functionality is still very similar though.
When some activity occurs on a repository you're involved in (or one you're watching), such as a new issue being raised, a new pull request, or a mention (@your-username) in an issue comment, you will get a notification by email and / or web, depending on your notification settings.
Your email notifications will appear in your inbox, and your web notifications will appear on your notifications page found here: https://github.com/notifications. You can reach this page by clicking the bell on the top right of your page.
If you're not currently watching a repo, you can choose to watch it by clicking the watch button at the top of the repo.
This will register you to receive notifications when there's new activity on the repo, as specified above.
You can manage your notifications settings here: https://github.com/settings/notifications. Here you can specify whether you'd like to receive email notifications, what email to receive email notifications on, and you can toggle automatic watching.
We understand there are some techie words used above, so hopefully these definitions will help clarify them! You will likely come across these terms when you begin exploring repositories.
Don't worry about fully understanding these development concepts, we've provided them in case you're curious as to what they mean!
Commits - This is the command that makes Github really powerful and useful. When a developer makes a commit, they are taking a snapshot of their work at that exact point in time, giving them a checkpoint to which they can restore their work to at any future time.
Branches - This is a facility which allows for multiple people to work on a project at the same time without confusion over version control. Developers branch off the current version of the project and make their own changes. When they're finished making changes, they can merge that branch back with the main project branch, which will then be the most up-to-date version.
Pull Requests - This is the method which enables the merging of changes from one branch into another. When a developer is ready to merge changes he or she will open a pull request, which is a chance for collaborators to review the changes and approve the changes to the project.
Thanks to GH Education for inspiration in sections as well as a useful article on readwrite.com!