Awesome

The United States (US) Research Software Engineer Association

https://us-rse.org

What is this?

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.

How do I contribute?

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.

Where is the page I'm looking for?

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.

How do I add an image/file?

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.

How do I add a job?

Please fill out the form. Jobs are reviewed for relevance.

How do I add an event?

Fill out the form, or see the events details page on how to create an event file directly.

How do I...?

Further content editing tips are in the details file

Pull Request (PR) Process

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.

What to Include

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:

1. 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).
2. 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.
3. 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.

Review Policy

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.

Checks and Tests

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.

Questions? Not sure what to do or what the problem is? Ask on the #website channel on Slack.

Supporting Documentation

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

Contributors

We use the all-contributors tool to generate a contributors graphic below.