DP Code Development Using Github Desktop

This is a companion page to the DP Code Development Using git page, and describes a way of using the GitHub Desktop app to contribute to code development at DP.

GitHub Desktop is available for Windows and macOS, and provides a simple user interface for using git/GitHub, rather than using the command line. If you prefer to use the command line, Git for Windows will install Git Bash (a shell where you can type git commands). If you are new to Git, and less familiar with using the command line, then GitHub Desktop can be a good way to start. Almost all recent Guiguts development has been done using GitHub Desktop. You can always switch to using the command line at any point. So far this page has been written by someone using the Windows version of GitHub Desktop, so there may be some minor differences for macOS users.

The sections below are parallel to the equivalent sections on the DP Code Development Using git page.

Initial repository set up

To get started with a git repo for DP, you have to first create a fork of the code repository under your GitHub user ID. You only need to do this once ever.

1. If you haven't yet, create a GitHub account.
2. Log into your GitHub account.
3. Go to the DP repo you want to work on and fork the repository by clicking Fork in the upper right
   • Click on your github username as the location to create the fork.
4. After a few seconds, this will take you to your forked copy of the DP repo under your username

This will create a fork of the code under your GitHub userid, eg: https://github.com/cpeel/dproofreaders

Cloning the repo

1. Install GitHub Desktop
2. Authenticate to GitHub in GitHub Desktop - essentially allowing GitHub Desktop to access your GitHub account.

On your GitHub page mentioned above, with the fork of the project, eg: https://github.com/cpeel/dproofreaders, use the green Code button to choose Open with GitHub Desktop. This will open GitHub Desktop at the Clone a Repository dialog. Here, you can change the location on your local computer where you want the cloned repository to reside, then choose Clone. You will be asked if you are planning to use the fork to contribute to the parent project or for your own purposes - you want to contribute to the parent project. Choose Continue.

Congratulations! You have forked the repository under your name at GitHub, and cloned it to your local computer. Your fork at GitHub is referred to by GitHub Desktop as origin, and the main DP repo you forked from is referred to as upstream.

Developing

Note that all of these steps only make changes in your fork, not the main repository, so feel free to play all you want -- you can't break anything.

1. Create a branch to capture the work you are doing: in GitHub Desktop, choose Branch, New Branch. use a branch name that is descriptive but concise.
   1. Near the top, center of the GitHub Desktop window, you can use the Current Branch pulldown to switch between branches. When that shows your branch name, you will be able to see the effects of any changes you have made. If you select Master, you will see the version without your latest changes. Note, if you are editing a source file, and change your current branch, your editor may ask something like, "The file has changed, do you want to reload it?" and you will need to decide if you want to load the version from the newly selected branch into your editor, or keep the one from the previously selected branch.
2. Make any changes you want using a standard git workflow:
   1. Make code changes and test them - these code changes can all be seen using the Changes tab in GitHub Desktop.
   2. Group logical changes into one commit.
      • In the commit section at the bottom left, the summary should be 50 characters or fewer and summarize the commit; the description should be lines of 72 characters or fewer with additional details. Note that you will need to press Return/Enter to break the lines - don't rely on wrapping within the description box.
   3. When you are happy with the summary and description, check the Commit button below that it is going to commit to the branch you intended - the branch you created above, not the master branch.
   4. Repeat the above editing and committing steps as needed
3. To push your changes up to GitHub for others to see, use the Push origin button at the top (may say Publish if it's the first time of doing it)

Note: If you have made changes, but haven't committed them yet, and you try to switch to another branch (e.g. you want to test the program without your changes so are switching to master) GitHub Desktop will ask if you want to take the changes with you, or stash them on the current branch. Usually you want to stash them and switch to the other branch. When you return to your development branch, you will see a message where the file differences usually display, saying you have a stash of files and asking if you want to restore them, which you normally do.

Merging your changes

After you have code you want merged into the main DP repository, open a pull request so devs can review your code.

1. Use the Create Pull Request button which will take you to github.com with the Pull Request ready for you to preview before creating it
   1. By default GitHub Desktop will have filled in the details using information from the Commit message. However, you should review this, especially if you have several commits, to ensure it will make sense to others who are reviewing the Pull Request
2. Click "Create pull request" to finalize the pull request

If, as a result of subsequent code review, you add some commits to your branch, use GitHub Desktop to Push Origin again, and your pull request will be updated automatically.

Refreshing your fork

The following walks you through refreshing the code in your fork to include updates since you forked. You will probably always want to update the master branch in your repo. If you have one or more code branches you're working on, you can update those too. These steps are not required to open a merge request.

1. To refresh your fork from the project master on GitHub (ie: the upstream repo) make sure you have selected the branch you want to refresh as your current branch, then use Update from upstream/master from the Branch menu.
2. You can push the refreshed branch back up to with Push Origin in the usual way

Reviewing code

There are multiple ways to review code, either that is just in another user's fork or that they've submitted in a merge request. Different people will want to do it differently, but here are some ideas:

• You can view the individual commits and the entire tree via the GitHub web UI.
• If they have created a pull/merge request, you can also also look at their commits, and test their code on your computer using the Current Branch pulldown, then the Pull Requests tab, and choose their pull request - this works like your branches do, so you can switch between it and the master branch or one of your branches in the same way.
• Their commits will be shown in the History tab, where you can see their comments, and the code differences.