Team Website Building
The purpose of this “course” is to add/update your profiles on the m2pi.ca website so that people can find the great work you’re about to do! Well split the session into two parts: In the first part we will use a common GitHub workflow (Pull Requests) to add profiles to the m2pi.ca website. In the second part (optional attendance) we will look at the system used to build the website and how you can use the same continuous integration tools to build a website for yourself or your team.
The m2pi.ca website is a static site build from this repository. We would like to include profiles for each of you on this website to help showcase your work. Since the website content is stored on GitHub we will take this opportunity to demonstrate a common but relatively advanced GitHub workflow to let you make the changes yourself.
Pull Requests: The basic idea
In your git and GitHub class you learned about using git as a tool for version control and how to set up remote repositories on GitHub. The main reason for hosting repositories in a public place like GitHub is so that you can share them and collaborate with others (e.g. Include a new feature you hadn’t thought of).
One model for managing a collaborative workflow is to give people write permission on your repository. This can work with people you trust, but it can be risky for others and can have unintended consequences; what if you only wanted someone was added to help you with the documentation but decided to reimplement everything in Fortran.
The most common alternative is the Fork + Pull Request workflow. This is a very popular pattern which lets people propose changes and then discuss them with the project maintainers until everyone is happy.
If you remember Marie’s discussion of git, when you clone a repository, a clone is a complete working copy including the entire project history (commits) from the original. When you Fork a repository on github a clone of the original is added to your account. You are free to make any edits you like to your fork (you have write permission on it) but crucially it will share a common history with the original. This means your changes can be isolated, reviewed and ultimately merged. In practice the workflow typically goes like this
- Make a fork of
- Make a new branch on your fork. Most new work happens in branches so that you can keep things tidy
- Open a pull request for your new branch against the main branch of
- The m2pi admins look at your changes. They’ll discuss your changes via comments on the pull request. They might request you make changes and push new commits to your branch.
- When everyone is happy the m2pi admins will merge your pull request which
will update the original
m2pi/super-projectrepository. Job Done!
This workflow lets any random person propose changes against any public repository and forms the foundation of a lot of software development workflows. Of course there are lots of variations (maybe you have merge conflicts, or the admins want you to rebase before committing etc.) but this is the general pattern.
Pull Requests: In Practice
Please follow the steps below to complete this part of the training:
- Visit the m2pi.ca github repository. In
the top right hand corner, hit the
- If you are asked “Where should we fork m2pi.ca” select your GitHub account
GitHub will say it is forking m2pi.ca for you. When it is finished it will take
you to your fork of the m2pi.ca website. If you look at the repository name in
the top right it will say something like “
yourusername/m2pi.ca forked from
There are a few ways to complete the steps below. I’ll do it directly through GitHub but if you have already set up your ssh keys for GitHub you can do this quickly on the CLI.
We should create a new feature branch before making any changes.
- At the top left of the repository, click on the branch button, it will
- In the little dialog that opens add a new branch name. Something like
yourusername-new-profilewill work (replacing
yourusername). Avoid spaces or other special characters in the branch name.
- Below the text area click
create branch: yourusername-new-profile
- This will create a new branch in your fork of the repo on GitHub. The branch button should now display your branch name.
We are ready to add the new profile information.
- Click on
content -> authors. Each of the folders/directories shown corresponds to a user profile on the website. Make sure you are in the right directory before proceeding.
Add file -> Create new file. This will open up a basic text editor on GitHub asking for a filename. We need to create a folder with your github username and a file called
_index.html(the underscore is important!) inside that folder. It isn’t obvious how to create a folder, but if you type your GitHub username in the filename box then type a forward slash (
/) GitHub should understand what you mean. Add
_index.mdas the filename.
- In the body of the file paste the following text
--- # Display name title: Your Name Goes Here # Username (this should match your github username) authors: - YourGitHubUsername # Role/position e.g. Graduate student role: Postdoctoral Fellow # Organization membership Organizations/Affiliations: organizations: - name: Your Current University url: https://www.google.ca # A list of your interests, add as many as you want interests: - Scientific Machine Learning - General Purpose Data Science - Mathematical Biology # Your educational history, add as many as you want education: courses: - course: PhD - Applied Mathematics institution: Univerisity of Alberta - course: BSc - Mathematics institution: Universidad of British Columbia # Social/Academic Networking, delete any items you don't want to use social: - icon: github icon_pack: fab link: https://github.com/pimsmath - icon: twitter icon_pack: fab link: https://twitter.com/carlosshigoto #- icon: linkedin # icon_pack: fab # link: https://www.linkedin.com/in/carloscontrerasc/ user_groups: - committee: members role: Project 1 member tags: - '2021' --- This is a freeform text area which supports markdown syntax. Fill in a couple of sentences describing yourself.
Some notes about the syntax of the file:
- There are two parts of the file: Metadata and Markdown. The Metadata makes up
most of the file and is enclosed between lines containing three dashes
---). Fields inside the metadata area use YAML syntax.
- Most of the YAML fields are specified as
key: valuepairs. Look at each field and updated if necessary. Make sure to update at least your name, github username and affiliation.
- Be very careful with syntax. YAML is sensitive to errors. whitespace and case matter!
- At the bottom of the file (after the last
---) you enter the markdown area. You can add a free-form paragraph in markdown format to describe yourself.
At the bottom of the webpage you will see a space for a commit message and some
options. Add a short commit message in the first box e.g. “Adding profile for
YOUR NAME”. There is also a radio button which will tell you where your commit
is going. Make sure it says the name of your new branch (e.g.
yourusername-new-profile). Hit the green
Create new Commit button.
You should be looking at the GitHub File brower again and the breadcrumb at the
top of the page should say something like
m2pi.ca/content/authors/YourGitHubUsername. Assuming it does, the last task is
to add a profile picture of yourself. Please try to find a photo of yourself
somewhere and save the file as
avatar.jpg somewhere on your computer.
Add file -> Upload File.
- In the dialog that opens up, click
Choose your files, then browse your computer to find wherever you saved
avatar.jpgand select it.
- Add a commit message (e.g. “Adding photo”), make sure you are commiting to
your feature branch and hit
If all has gone well, GitHub will have noticed that you have a new feature
branch and offer to help you make a pull request. Click the Green
Compare and Pull Request button. In the new window which opens you will be sending a
message to the m2pi admins. Add a message describing your changes and hit the
Create Pull Request button.
In a typical workflow you would now be expected to keep an eye on that pull request for any discussion with the project maintainers. This can sometimes be a long process but since our changes are pretty simple that shouldn’t be too complicated. You might notice some automatic messages attached to your pull request related to building a preview of the website. If the preview looks good with your changes I’ll try to merge it right away. If there are any problems I’ll send you some instructions via the comment area in your pull request.
- Install hugo
hugo new site teamX-project-site
git initthe new site
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
hugo serve -Dto preview your site at http://127.0.0.1:1313
- hugo new post/kickoff.md
- Change background image and color
- Push repo to github
- Connect repo to netlify
- Specify netlify config in
- Create a branch and add mathjax
- Preview deploy branch
- Merge PR to publish to live site.