Contribution to this repository is via the fork model. Contributors push changes to their own “forked” version of workshops, and then submit a pull request into it requesting those changes be merged.
To get started:
- Fork the repo by clicking Fork in the top right corner:
- From git bash, run (replacing [user-name] with your GitHub user name):
\> git clone https://github.com/[user-name]/workshops.git \> cd workshops \workshops> git remote add upstream https://github.com/NuevoFoundation/workshops.git \workshops> git remote set-url --push upstream no_push
The last command prevents an accidental push to this repository without going through a pull request.
After running above,
git remote -v should show something similar to the following:
\workshops> git remote -v origin https://github.com/dmonroym/workshops.git (fetch) origin https://github.com/dmonroym/workshops.git (push) upstream https://github.com/NuevoFoundation/workshops.git (fetch) upstream no_push (push)
Build and Test
In order to build and test your changes you’ll want to use hugo. If you’ve followed the right installation instructions then hugo should be in your PATH (if not give your machine a restart).
\> cd workshops \workshops> hugo -D server
This will output some build information but the most important line is going to be along the lines of:
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
You can now launch your favorite web browser and open up //localhost:1313/ and should see the site up.
Updating your fork
In order to keep yourself up to date you’ll want to maintain your fork updated as much as possible. Before creating a new branch you should fetch the changes and push them to your fork. Here’s how to do it (if you need another branch just use that instead of master).
\workshops> git fetch --all --prune \workshops> git checkout master \workshops> git merge upstream/master \workshops> git push origin master
Scenario: Let’s make a simple change to the Getting Started page and submit a pull request.
Follow instructions above
Once you’ve followed the Code instructions above you’ll have a local copy of the workshops repo.
Create a topic branch
Make sure your fork is updated before doing this:
\workshops> git checkout master \workshops> git checkout -b [branch-name] \workshops> git push --set-upstream origin [branch-name]
Open the repo using VS Code
When you launch VS Code you can Open Folder… Navigate to the workshop folder and select open.
Navigate to file and modify it
Depending on what you’re modifying you’ll want to get a better understanding of how the site is built
In our case you want to modify this file so go to content\english\guidelines\getting-started.md I simply want you to add two exclamation points to the word “Welcome!”
Commit the change
git status should provide you with all the changes you’ve made and all the file names. You’ll want to stage them by using git add and then commit and push them. Here’s the commands to do that.
\workshops> git status \workshops> git add content/english/guidelines/getting-started.md \workshops> git commit -m "Added exclamations" \workshops> git push
Some git tips: If you want to add everything and commit at the same time you can skip all these commands and just use
git commit -am "message here" and then do the
Create a pull request
Congratulations, you’ve now made all the necessary changes and the last step is to get it reviewed and pushed into production.
If you navigate to your fork on github.com you will most likely see a suggestion to create a Pull Request based on your latest push.
If you don’t, just navigate to Pull Requests -> New pull request
The most important aspect here is to make sure you’re choosing your branches correctly (your base and your head).
You can now hit the Create pull request button, give it a description and good title and wait for a reviewer to approve so it can be merged.