Chapter authors: Submitting new and revised content - ubc-geomatics-textbook/docs GitHub Wiki

To facilitate continual textbook contributions for the remainder of the project we will utilize Git branches. Branches will allow us to modularize and define changes being made to the textbook, and ultimately help us to monitor who is doing what and when.

The textbook is now deployed live on GitHub pages using the repository's main branch, so we need to avoid making pull requests directly to that branch so that we can test and debug and new changes before making them publicly viewable. The way we will do that is through a new branch called develop. The develop branch is now where we will merge any changes submitted through pull requests. Once we have tested the new changes, develop will be merged into main so that the site will be updated live.

Your forks currently sync with the main branch, and so will need to be switched to the develop branch. The easiest way to do that is to delete your current fork, and start fresh with a new fork.

Create a new fork

Delete your existing fork by going to Settings tab and scrolling to Danger Zone. Deleting your fork will also delete any work you've made since you submitted your last pull request.

Once your fork has been deleted, you can create a new fork of the central repository. Your new fork will now have "This branch is even with ubc-geomatics-textbook:develop." just below your tabs in GitHub.

Now you can clone this forked repo to work locally.

Create a new Issue

Create a new GitHub Issue in the central repository by using the New/revised chapter content template. You can do that here.

Using this template, provide a title, description of the content, and deadline

Create a local branch for your new Issue.

On your fork, you can create a new branch for your work and give it a name to tie it to the Issue you submitted. This will help us review your code later when you submit a pull request. To do this, make sure you are on the develop branch of your fork:

git checkout develop

Once on develop, create a new branch and give it a name that includes the Issue number and very short keyword description:

git checkout -b <issue-number-and-description>

If you use the git branch command, you will see the two branches on your local machine. An asterisk will appear next to the branch you are on.

Push your new branch to GitHub

Use git push to connect your new branch to your fork.

git push -u origin <issue-number-and-description>

Now, you can work on this branch as you would normally, changing files and adding commit messages.

Push new content to your branch

Once you are ready to push new content to your branch on GitHub, you can use git push once again (make sure you are on your new content branch).

git push

Submit a pull request

When your content is complete and you would like to submit it to the book, make sure it is pushed to your fork. Then, you can submit your content branch through a pull request. When submitting your pull request, be sure to submit your branch to develop on the central repository.