Contributing to Cayden's Guides

Thank you for the interest in contributing! All types of contributions are encouraged and valued. These are community guides that couldn’t exist without the help of volunteers.

Please see the Table of Contents for different ways to help and details about how this project handles them. We look forward to your contribution(s)!

Table of Contents

Things to Know

Before contributing, please make sure you read through this section to ensure your contributions can be accepted.

Design Philosphy

At the core, these guides are intended to reduce the barrier to participate in our community. The guides should be focused on things specific to our community and how our community interacts with those things.

It is also important that anything contributed to the project can be maintained. If a new guide is needed then we will need to know someone is willing to help with both writing and maintaining it. A guide that becomes stale with old info may need to be marked as inactive (meaning that it won’t be visible on the website, but will still be part of the project files in case someone wants to update them).

Markdown

The guide pages are formatted in markdown. If you haven’t used markdown before then fear not, it is relatively simple and you can find a syntax guide at the Markdown Guide’s ‘Basic Syntax’ page..

Simple Page Edits

Editing pages can be done by finding the pencil icon in the top right of any page when navigating the website. Clicking that icon will bring you to a page where you can make the changes in your web browser (you will need a gitlab account). When you’ve made the changes you want to make then in the commit message section write a short description of what was changed (Fixed typos, clarified X, etc). Then click on Commit Changes. From there the changes will need to be reviewed by a project maintainer before they appear on the website.

Adding New Content

Requirements:

Adding new content requires a few steps to set-up a development environment:

  1. Install Hugo. Hugo is the software used to create the website, and it will allow you to live preview your changes before committing them to the project.

  2. Install an Integrated Development Environment (‘IDE’) if you do not have one already. An IDE allows you to edit the project files and submit the changes to the project. If you don’t have an IDE already, then install Visual Studio Code (‘VS Code’).

  3. Clone the project’s repository. To do this go to the main project page. There you will see a button that says Code. Click on that and select Visual Studio Code (HTTPS). Your browser may ask you to confirm to open the link in VS Code, if so click yes/agree. VS Code will then ask you to select a location to save the repository. For this guide, save it in your user folder. It will create a new folder called caydens-guides. If you select some other folder then remember this location.

Walkthrough:

  1. Navigate to the folder where you saved the respository (if you followed the above instructions, this would be in your userfolder/caydens-guides. Open the folder, then right click and select Open with Code). This will open the project repository in your IDE.

  2. Next, click on View -> Terminal. At the bottom of the screen a terminal window will open up, and there will be some new icons in the top-right of that portion of the screen. Next to the New Terminal (plus icon) there is a drop-down arrow that lets you select the type of terminal you’re opening. Click on the arrow and select Git Bash. This opens a Git Bash terminal in that bottom part of the screen. Within your git bash terminal type hugo server and hit enter. After a few moments you’ll see the terminal say a few things including the line Web Server is available at http://localhost:1313/ with a link. Ctrl+click the link and it will open a local, live preview of the website. Now any change you make will be able to be previewed.

  3. Adding content can be done following the Hugo instructions. You can follow step 2 to open a second git-bash terminal to add new pages, or in your first terminal you can press CTRL+C to stop the live preview to add new pages and then use the hugo server when you’re ready to live preview again.

    a. On the left side of the Visual Studio Code you can also see a list of files for the project.

    b. In the content folder you can navigate to individual pages and make changes.

    c. If you need to use images, store those in the static/images folder.

    d. In addition to Markdown being used, the website theme also provides some additional features like notice boxes, expandable/collapsable sections of text, and more.

  4. When you are done making changes and are satisfied with how things look in the live preview, then in you’re ready to commit your changes. In Visual Studio Code on the left hand side click on the source control button (It will have a number in a bubble showing how many files you have added/changed/deleted).

You do not need to use the hugo command to build the site. This is done automatically when changes are merged into the project repository. You can use the hugo server command to do the live preview.

  1. Once youre in the Source Control Panel, we’ll prepare your commit:

    a. There is a section that lists Changes with each file that was changed. You can click on each file and it will show the file comparing which lines of the file were added/deleted. This is useful to see what parts of a file were changed. When you have previewed a file and are okay with your changes, press the Stage Changes icon (looks like a plus sign) next to the file name. This will ‘Stage’ the file meaning it is ready to be committed. Repeat this step for each file that you have changed. If you updated a file in error you can click on the Discard Changes arrow button next to the file name which will revert any changes you made to that file.

    b. When you have reviewed all files and staged all the files you want to commit, then in the Source Control Panel you’ll see a spot to put in a commit message. Write a short description of what was changed (Added X Guide, Fixed typos, clarified X, etc).

    C. Once you’ve typed a commit message, hit the Commit button. Lastly, you’ll need to push the changes to the project repository.

    d. You may be asked to fork the project, if so then click yes. Then make your commit and push the changes. Once this is done you should be able to go to the main project page and there will be a banner prompting you to create a Merge request.

Other Ways To Contribute

work in progress

  1. Reporting bugs
  2. Improving Documentation