This document contains the technical details on how to set up Hugo (to see your edits locally before pushing them to GitHub), and how to prepare a pull request to make changes to content on the devopsdays website.
If you'd like to assist in contributing to the code itself (as opposed to the content) of the website, please see the devopsdays-theme CONTRIBUTING guidelines.
If you'd like to edit a specific devopsdays event site (and/or contribute code), here's how to get started:
- Have the ability to run Hugo. This can be done locally or through Docker.
- Fork this repo and clone a copy locally.
- Start docker
- Run
./hugoserver.sh
from the root of this repo.
- Install Hugo. Use the Hugo version that we use in .github/workflows/hugo.yml file. (Quick Install) Examples of hugo installation with a version:
- maxOS:
brew install hugo@0.67.1
- linux:
brew install hugo@0.67.1
- windows:
choco install hugo -confirm --version 0.67.1 --allow-downgrade
To watch for changes and rebuild on the fly, open a new terminal, change directories to your fork of the repo, and execute the following:
# Run through Docker (recommended)
./hugoserver.sh
or
# Run with your local Hugo installation
hugo server -w --baseURL="http://localhost:1313"
Now open http://localhost:1313
in a browser and navigate to the content that you're editing - voilà! Note: hugo's watch
is not going to catch every change, so if you're making structural/file or date changes, consider Control-C and restart of the watch
command.
When running the hugo server -w
command listed above, you may get an error about "too many open files" or "fatal error: pipe failed". To solve this, run the following commands in your terminal:
sudo launchctl limit maxfiles 65535 200000
ulimit -n 65535
sudo sysctl -w kern.maxfiles=100000
sudo sysctl -w kern.maxfilesperproc=65535
Note that these changes will not persist past a reboot of your computer, so you'll need to run them again if you restart.
Make your own fork of the devopsdays-web
repository.
Add the source repository as a remote called "upstream":
git remote add upstream git@github.com:devopsdays/devopsdays-web.git
or
git remote add upstream https://github.com/devopsdays/devopsdays-web.git
You only need to create your fork once, as long as you don't delete it.
- Before starting any new change, it is essential that you
rebase
your local repository from the upstream. You may think that working from your fork is enough, but sometimes upstream changes will affect your work in ways you may not anticipate, so you'll want to stay current. Issue these commands:
git checkout main
git pull upstream main --rebase
This confirms you are on the main branch locally, and then applies the changes from the upstream to your copy.
- Create a new local branch for your changes. This helps to keep things tidy!
$ git checkout -b fix_that_thing
(Replace fix_that_thing
with a quick description of your actual change.)
- Make your changes, test them locally (see above - the
watch
command sometimes needs a restart), then push that branch up toorigin
on your fork.
$ git push origin fix_that_thing
- Submit a Pull Request for the branch you just pushed. Please title the pull request according to the event affected, i.e.,
[CHI-2017] Add Bluth Company as a sponsor
- Optionally, open your pull request in a browser and look at the preview that
Netlify
(a build tool) built. - You can mention on devopsdays Slack's #website if you'd like a PR merged quickly. (Availability of maintainers varies.)
- When a commit is merged to
main
on GitHub, Netlify will automatically build the site and publish it to https://www.devopsdays.org.
- Code changes for devopsdays-theme should be made in a different PR from event content updates.
- We use github issues to track work, so feel free to create new issues if you like (or read/comment/work on existing ones).
- If you are proposing a change that affects the overall site, and is not tied to an existing issue, please open a new issue so that it can be discussed by the team, prior to submitting a pull request.
- If you're using CRLF line terminators (like on Windows), the site won't build correctly if the first
+++
line of frontmatter in speaker and program files ends in a space like+++
. The workaround is to remove the trailing space.
- A maintainer will merge the PR if it is mergable, as soon as the checks pass.
- If you do not want your PR merged immediately, in most cases you should not open the PR.
- Our workflow guide provides solutions to most
WIP
use cases without opening a PR. - Questions about specific cases not covered in the guide can be asked in the #website channel on devopsdays Slack.
- In general, only make changes to event content files. "Event content" means anything inside the
/content/...
,/data/...
, or/static/...
directories. - Changes to event-specific content should be submitted in a separate PR from changes to more general content for the whole site.
Generally speaking, you should avoid storing any files other than logos or small images inside the repo itself (out of consideration for your fellow devopsdays organizers who have to pull down this repo). Please follow these guidelines:
- Do not upload presentations or other artifacts from your event into this repo. Either link to the presentation on Speakerdeck/Slideshare from the presenter, or even better, create a Speakerdeck account for your event and put the presos there.
- Small web images are fine (logos, etc). If you have high-resolution versions of your logo to share with others, please do not host them on the devopsdays-web repo.
- It is acceptable to add in a single PDF for your sponsor prospectus if you desire (in
static/events/YYYY-city
), but please keep this file under 3 MB. It is better to host it on Google Drive or something similar, and then link to it from your site. - OPTIONAL - you can host your PDFs for prospectus, etc, in the repo at devopsdays/devopsdays-assets and then link to them from there. Files in that repo are presented under their relative URL at https://assets.devopsdays.org. For example, the file located at
static/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf
in thedevopsdays/devopsdays-assets
repo will be presented athttps://assets.devopsdays.org/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf
If you have permissions to merge PRs on this repo, here are a few guidelines to consider:
- Is the requestor authorized to make changes for that event? They need to appear on the contact list for the year and city they're editing.
- Do not allow any PRs that change files outside of the above-mentioned "content" directories. Especially watch out for
.gitignore
,config.toml
,config-windows.toml
, and anything in thethemes
directory. GitHub will require a review from certain maintainers/admins if specific non-content files/directories are included. See CODEOWNERS for specifics. - Check to see if the tests pass, but use your judgement on merging something that fails (see "PR Tests" below for guidance)
- If you are unsure about merging a PR, please use the "request a review" button on the PR to request one from other maintainers.
- If you're reviewing all the details of a PR before merging or are communicating with the Submitter, add yourself to Assignees so that others know someone is waiting on a response or reviewing all the details of the PR thoroughly. Be sure to also add a comment into the PR that you are reviewing it, and if you need a change from the Submitter prior to merge, be sure to label the PR as
do-not-merge
.
The following tests run when a PR is submitted:
- GitHub Actions - a set of tests that confirm that all files are lowercase (in order to be friendly among all platforms people may use), that the site can be built with Hugo on Linux (ubuntu-latest) and Windows (windows-latest). There is also a test in which gulp will run html-min in order to identity if there is any invalid HTML. All three jobs (lint, build on Linux, and build on Windows) are required in order to deploy with Netlify -- regardless if the Netlify test passed or not.
- Netlify - this test builds the site, and hosts an ephemeral preview version of it (viewable by clicking on the "details" link next to the test once it has turned green). It's a good idea to view this "deploy preview" if the PR has changed anything significant (adding a sponsor, etc, probably not...but changing content in a large way? Yes.)
If you wish to show someone else your local changes without creating a pull request or committing you could utilize netlify dev.
Firstly make sure netlify dev
is installed
npm install netlify-cli -g
If you're not authenticated with netlify, do so with the following command. Note that you may need an account.
netlify login
Now use netlify dev
to share your local changes
netlify dev --live
You'll then be given a URL to share:
Waiting for localhost:1313.
Connected!
◈ Installing Live Tunnel Client
◈ Creating Live Tunnel for 33459a04-9379-473d-8517-a25a208ef36a
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ ◈ Server now ready on https://devopsdays-web-936f59.netlify.live │
│ │
└──────────────────────────────────────────────────────────────────────┘
Thanks to Jess Frazelle @jfrazelle for clueing us into the awesome previews with Netlify!