These are the files for the official US RSE community website hosted at https://us-rse.org. The site is built with Jekyll and hosted on GitHub.
Members of US-RSE have access to the organizational Slack space. The #website channel, referenced frequently below, is part of that space. It's the best place to ask questions and get help.
We encourage the community to contribute to the content of the website.
To do this: fork the repository, make your proposed changes, and then create a pull request against main. More details below.
The webpage text exist in markdown files (.md) in several places like _events, _pages, and wg. The best way to find the page you're trying to edit is to follow the path in the URL of the page itself. Example: editing the page for "https://us-rse.org/events/2022/2022-10-funder-talk-series/" would be in /_events/2022/2022-10-funder-talk-series.md
Can't find what you're looking for? You're not alone. Ask on the Slack #website channel.
Small files like .png images go into /assets/img
Larger files like slides from a speaker series currently go into a read-only Google Drive. One exists for the speaker series here.
- You'll need to ask to add slides to that folder if you are not an editor.
- Managers will need to change the permissions of files added there to be read-only and provide a share link that is accessible to anyone with the link to view.
Please fill out the form. Jobs are reviewed for relevance.
Fill out the form, or see the events details page on how to create an event file directly.
Further content editing tips are in the details file
If its been a while since you've last worked on the site,
you'll notice that several commits were made by bots, with
the author name github-actions. These are
automated commits that are part of our continuous integration (CI)
suite, and they help keep the site up-to-date and running smoothly
by automatically updating data like the Job Board. You can safely
ignore these commits when reviewing the site's history, but when
contributing, you may wonder how to deal with them. Worse still,
if you forked the repository, you may encounter a bot in your
fork doing the same. When you open your fork on GitHub, these
commits might put you "Ahead" of the upstream/main branch, when
in reality you just had a different bot committing the same changes
in response to the same triggers.
This cannot be automatically merged, and if you submit a PR with your fork's commits, including the bot commits, it could cause confusion as additional commits are added, or worse — it could cause a merge conflict and a minor headache for you for the next 20 minutes.
To prevent this, it's recommended to strictly and forcefully pull the latest
changes from upstream/main into your fork before you start working.
First, in GitHub, make sure to click "Sync Fork" to get any
updates. It will be at this stage that you'll notice that,
even though you just asked GitHub to send you the latest work from USRSE,
your fork is n commits ahead of the upstream/main branch. These are the
bot commits.
On your local machine and in your local repository, grab the latest changes from origin remote (your fork):
git fetch origin main
git pull origin main
Then, fetch the latest changes from upstream remote (the USRSE repository):
git fetch upstream main
Then, diff your local main against the upstream main:
git diff main upstream/main
You should see that there are no changes, which means that your
local main is up-to-date with the upstream main. The bot in your fork added
commits, but the changes were identical to the upstream bot's. If this
is true, you can safely reset your local main to match the upstream main, which will remove the bot commits from your local history:
git reset --hard upstream/main
Then, push the changes to your fork, which will update your fork's main branch to match the upstream main branch:
git push origin main --force
The use of --force here is necessary, because you are essentially
telling your fork to discard certain commits, which git never wants
to do by accident. In this case, it's totally safe! Your fork on
GitHub should now be "even" with the USRSE fork!
PRs should be made on the main branch only.
Those who have full permissions to the repository should still be working on separate branches and creating PRs for any changes.
Give the PR a descriptive title. The PR template asks you for a description of the changes - a brief description is fine for simple/routine changes.
Three things to do after creating the PR:
- Preview the site, either locally (necessary for complex functionality changes - see docs/local_previews.md for details) or with the CircleCI preview (fine for routine content changes and additions - see docs/tests_ci.md for details).
- Ask others to review content if needed. For example, if your change is part of a working group's activities, you may need to check with other members of the working group to review your update.
- Once the content is settled, post a link to the PR on the Slack #website channel to get reviewers for functionality and basic website style conformity.
PR reviews are not content reviews. While corrections to basic grammatical issues, links, clarity problems, etc. in the files that are part of the review can be noted, the content of things to be posted to the website should generally be discussed and resolved before creating a PR. If you create a PR that needs a content review before a technical review by the website group, please note that in the PR info.
Those with merge permissions on the repo: use your judgment as to whether you need a reviewer. Routine edits, additions, changes that are part of the normal activities of US-RSE do not need to be reviewed unless you want. For larger edits (things requiring discussion or assistance), please ask for someone else to review. Generally "squash" when merging.
For those without merge permissions:
- 1 reviewer for routine/small edits, additions, and changes. If you get a review from someone who doesn't have merge permissions, ping the #website channel on Slack to let people know your PR has been reviewed but needs to be merged.
- 2 reviewers (and likely discussion in the PR, an issue, or the Slack #website channel) for changes to the layout, functionality, or style of the website
Anyone in US-RSE who is familiar with the website is welcome to review PRs.
Want merge permissions? Join the #website channel in Slack, help out a bit with tasks that come up, and then ask - we're happy to have new website maintainers.
When you create a PR, automated tests run; see docs/tests_ci.md for details.
What the PR submitter is responsible for:
- URL Checker: This does NOT check internal relative links on the site, only absolute/full URLs. If the URL checker fails, click on the Details link, and then expand the URLs-checker section of the report that comes up to try to find the failed URL.
- Failed URL in a file that is part of your PR: you must fix it.
- Failed URLs in the job listings: OK to ignore
- Failed URL check where you know the URL is actually OK: OK to ignore.
- Failed URL on another page outside of your PR: fix it if you can. If you can't fix it (not sure what to replace it with, etc.), please note the problem in the PR discussion. The person who merges the PR may choose to ignore the issue.
- Spellchecker: Click on the Details link, then expand the Check Spelling section of the report that comes up to identify the issue.
- Spelling issue in a file that is part of the PR: you must fix it. If it's a legitimate word, you may need to add an exception to
.github/workflows/typo_config.toml - Spelling issue in a file that is not part of the PR: this generally shouldn't happen, as previous PRs have also had the spellchecker run.
- Spelling issue in a file that is part of the PR: you must fix it. If it's a legitimate word, you may need to add an exception to
Questions? Not sure what to do or what the problem is? Ask on the #website channel on Slack.
More details can be found in:
- docs/events.md: formatting for events, how the events and calendar work
- docs/details.md: redirects, embedding videos, last modified dates on pages, etc.
- docs/tests_ci.md: further details on CI processes
- docs/local_previews.md: how to run and preview the site locally on your computer
- docs/feeds.md: RSS and JSON feeds available for the site
We use the all-contributors tool to generate a contributors graphic below.
