Pull Requests
If you feel that you are doing something other Hyak users would benefit from knowing about we invite you contribute to this website! You can contribute anything you think might be helpful, such as a guide on a tool or program you learned for your project or just tips and tricks you would like to share. We have tried to make this process as streamlined as possible, so much so you can do it completely from your browser without having to install anything on your system.
Setting Up the Environment
In order to make the process as easy as possible we take advantage of Github Codespaces to provide a quick pre-configured development environment for contributors, which provides 60 hours of use and 15gb of storage a month to free github users. First go to the UWrc github repo and create a fork by clicking the "fork" button at the top right. You will need to have a github account for this step, so you can either already be logged in or just create one when it asks. Inside of your forked repo select the green "Code" dropdown, go to the "Codespaces tab", and click "Create codespace on src". Github will automatically start setting up your codespace in another tab using the browser version of VisualStudio Code, which may take up to a couple of minutes. This should work out of the box on chromium based browsers but if you are on firefox you may need to disable the cookie blocker by clicking the shield icon near the search bar and toggling the "Enhanced Tracking Protection" option.
While github codespaces are the fastest option, they aren't the only one if you would like to setup your environment locally or just through a more flexible online environment since we use the open source devcontainer format to build our development environment. If you would like to setup an environment locally you can of course install VisualStudio Code with the Codespaces extension, but I recommend looking into the open source project Devpod, which will allow you to create a docker, kubernetes, or other online hosted environment using your preferred IDE just by copying and pasting the forked repo url. There are also other cloud providers, such as Gitpod, that provide similar services. If you would prefer to setup the environment directly on your machine there are instructions on the UWrc readme.
Writing your Webpage
Once your environment is up and running you have to actually write your new webpage, which we provide a couple of tools for. There is a built in spellchecker and markdown linter (style checker) set up for you so make sure to go to the "problems" tab in vscode to see all spelling and style errors and simply right click to select a fix. Some of the existing pages might not follow the guidelines perfectly but just make sure yours doesn't have any problems.
For actually writing your webpage, we have a Markdown Guide you can read to learn some of the capabilities of markdown, and there are also countless guides online for anything you might want to do. To help you write your webpage there is also a markdown extension installed for you that provides helpful shortcuts detailed in their Documentation. After you write the page you have to link it to the existing site structure (namely to the sidebar), which we detail in the Linking Markdown guide.
While writing your webpage we recommend that you make frequent commits using the source control tab (the icon with a dot branching off of a line on the left sidebar) in the format "Add/Update/Fix/Remove: what you added, updated, fixed, or removed" after adding or removing each subsection. For example you could write "Add: Introduction to guide" after writing the introduction to your page. To make a commit just select the plus icon on the files you would like to add in this commit, add your description in the text box, and either press "Commit" or select the dropdown and press "Commit & Push". Pushing is just adding all of your changes, including ones from previous unpushed commits, to your remote repository. You can manually push at any time by selecting the ... "More Actions" button next to the "Source Control" title and selecting pull, by bringing up the command palette and searching pull, or by pressing pretty much any button labelled sync. If push fails you probably need to update your repo because it got out of sync with the remote repo. If that happens just go to the terminal and type sync (which is actually a shortcut for the github command line tool command gh repo sync (remote-repo)) and git pull --rebase, which will attempt to pull and combine any commits from the remote repo to yours.
It's unlikely you'll get everything right first try though, so there are a couple of ways to preview your page while working on it. VScode has a built in preview that you can use by clicking the two pane icon with a magnifying glass on the top right of your window, or pressing Ctrl+K and then v. This will open a preview of your rendered webpage in another tab but unfortunately won't render some things that we render manually, like the tip box above. To view your fully rendered page, and check that the sidebar is configured properly, you can run yarn start in the terminal (you may need to open one by pulling up the Command Palette with Ctrl+Shift+P and searching for "terminal") which will load up a preview of the entire website and automatically open it in a another browser tab for you. The site will automatically update whenever you make changes, but you can restart it by pressing Ctrl+C in the terminal and typing yarn start again.
Contributing to Hyak Documentation
Once you are happy with your webpage and all your changes are committed to your repo you can finally add it to the official documentation site. When you first pushed from your codespace to the UWrc repo, Github actually forked the repo automatically (which just means it made a copy of it on your own account) and started committing to that since normal users can't change the UWrc repo on their own. That means your changes are all only on your account right now and you have to submit a Pull Request to merge them with the UWrc repo from yours.
In order to submit a PR all you have to do is type the command pr <title> (which is also a shortcut that first runs sync, git pull --rebase, git fetch upstream and then gh pr create) in the terminal, where title is a descriptive title of what you changed in your PR. You can double check that the command worked by going to the Pull Requests tab on UWrc and seeing if your PR is there. Once you have submitted your PR make sure to come back and check periodically since the maintainers may have some questions about it. If you have any sort of notifications enabled for Github you should get them for any comments on your PR.