Website contribution quick-guide

03 Oct 2018

There has been interest in contributing to the website, but not everyone knows how to go about that. I’m going to outline some basic steps below. If you’re already familiar with git and github hosted webpages then this will be a lot of review.

At a high level we want to do the following:

  1. Have a fork of the source code associated with our user on github
  2. Clone our repository to get access to the source code
  3. Create or modify files as needed
  4. Add the new/modified files to staging
  5. Create a commit (with useful message)
  6. Push the changes to the remote repository
  7. Create a pull request explaining your changes

Step 0 Before we can begin step one, we need a github account. If you don’t already have one, head on over to github. Otherwise sign in and proceed.

Step 1 Head to the repository and click the fork button. This creates a copy of the repository under your user account which you can experiment with until you are happy with the final result.

Step 2 From your forked repository page on github, you will be able to get a checkout link from the green clone or download button. If you are using a command line git client you can then use the following command to check out a local copy where [yourUsername] is replaced with the username you created/signed into in step 0:

git clone https://github.com/[yourUsername]/ColaMakerspace.github.io.git

Step 3 If you are creating a post, you can go ahead and create a new file in the _posts directory. All files in that directory are organized by date and are written in markdown. I found the following very useful while writing this post in markdown: markdown cheatsheet.

Step 4 With the amazing changes now complete, run the following command to stage the changes you want to commit:

git add [filename]

This can be done for each file you want to add. To view which files you have currently staged you can run the following:

git status

Step 5 After all desired files are staged, use the following command to commit them:

git commit -a "your amazingly descriptive message explaining how great your changes are"

Step 6 Next, push the changes to the remote server with:

git push origin [nameOfBranch]

If you are not sure what your branch name is, run:

git branch

If your changes are a markdown file, they can be easily previewed by opening them in the github repository source code browser. This is a good way to validate that markdown formatting is working as intended. If your changes are more structural to the website, more thorough testing should be done.

Step 7 Finally, with all the changes back on github under your account you must create a pull request. To do so, go to your forked repository and click the New pull request button. This prompts you for a description and/or comments which may help the admin understand your changes. After the admin accepts the changes they will be merge the pull request into the production repository. From there it will be automatically deployed to the website. If the admin or community at large have questions or concerns, then the pull request becomes the forum to discuss and resolve any issues.