This is a repository that containers 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.
We encourage the community to contribute to the content of the website.
To do this: fork the repository, make your proposed changes, test locally (see below), and then create a pull request against master. For more details about opening pull requests and issues, see our Contributing Guide.
The map is generated programmatically from the US-RSE member list, so if you have already joined and provided your institution, you should be represented on it. If you see any issues or errors with location lookup (we use geolocation of a named location) please open an issue.
We maintain a list of current and previous job postings in _data/jobs.yml. You can add a new job to this list, and so that newer jobs appear at the top, we ask that you add the new entry to the top of the list. Specifically, we ask that you provide a name, location (can be Remote), an expiration date, and a url to the posting. The expiration date is not shown on the page, however it will determine when the job doesn't appear anymore. We suggest setting a timeframe such as a month, and if you want to extend it, you can open a pull request to update the date. An example posting is shown below. This job would appear on the site until the first of July, 2019.
- {expires: 2019-07-01, location: 'Princeton, NJ', name: 'Research Software Engineer',
url: 'https://main-princeton.icims.com/jobs'}And don't forget to write your new job at the top of the _data/jobs.yml file!
For testing, we look to see that all fields are defined, the url exists, and that the "expires" field loads
as a datetime.date object in Python. If you copy the format above, you should
be ok.
You can add an event or training to the site by adding a markdown file in the _events
folder, organized by year. Do not use the full date (e.g. YYYY-MM-DD-.md) in the file name,
Jekyll will not post pages that it interprets to have a future date in the filename. A better option is
to use a partial date (e.g. YYYY-MM-.md).
Here is an example of a file in _events/2019 for PEARC19:
---
title: PEARC19
location: Chicago, IL
url: https://www.pearc19.pearc.org/
expires: 2019-08-01
event_date: "November 17–22, 2019"
layout: event
repeated: false
---
Join us at [PEARC19](https://www.pearc19.pearc.org/) for a Birds of a Feather (BOF) session "Building a Community of Research Software Engineers." Our session is scheduled for 5:15 PM on Monday, July 29.The top section is frontend matter that must include the title, location, url, layout as "event" event date, an expiration date, and a "repeated" variable (true or false). Notice that the event date is a string that doesn't get parsed, while the expires must be a date in the format shown. The bottom section (the content) you can write any amount and length of markdown that is desired. When the event is active (before expiration) the full content will be shown on the "Events and Training" page. Once it expires, it will move into the events archive. In both cases, clicking on the Event will take the viewer to it's page, and they can view additional content and the url provided. In the case of the archive, the bulk of content is only viewable on this page.
You'll notice that there is a folder called "repeated" in the events folder:
$ ls _events/
2019 2020 repeated
A repeated event is one that happens weekly, monthly, or on a regularly scheduled basis that typically does not change, meaning that you wouldn't need to update the post. A weekly call that has a description and a consistent link to an agenda would be appropriate, while the same call that varies in schedule or requires an updated description would not quality. An annual event, or one that would require a different description, would not be repeated, and should be placed in a folder named by date. Repeated events are always shown at the top of the events page, and do not expire.
A community document is a living document that represents a community effort to discuss a question or idea. We call it "living" because we encourage community members to edit and contribute to the documents over time, and so there isn't a "publish" date associated with it. For this reason, we use the wiki associated with the repository here.
If you ever need to clone this content, you can do:
$ git clone https://github.com/USRSE/usrse.github.io.wiki.gitNOTE: During the testing phase of the living documents, we currently plan for the wiki to only be editable by community (repository) members.
To edit a living document that already exists, you can browse the wiki to find it and then update it. Generally, we are organizing topics as they are added, so if you want to add a new category or change the existing organization, please do so.
If you want to add a new document, while you might add it directly to the wiki, it's recommended to get others involved first. You can ping others in the USRSE slack to contribute, and it's also recommended to start the document as a Google Document for easier commenting and editing, and then move to the wiki when it's in a final first draft state. For all community documents, the following points apply:
- It's strongly suggested to first work on your document in Google Docs or similar, where you can bring in multiple community members to put together a first draft. Importantly, you should make sure that the content adheres to the US-RSE Code of Conduct. It is suggested that you have discussion and work on the document with at least two other community members before submitting the document to the wiki. You should feel that it's in a solid "first draft state" before doing a submission.
- Make sure that you verify the following:
- the content is of interest to the RSE community
- the content does not violate the Code of Conduct.
NOTE: Any material added to the wiki that does not follow these rules is subject to removal. If you see content on the wiki that is not appropriate or otherwise breaks these rules, please open an issue on the repository immediately, or contact the steering committee.
If you want to start a community document and would like some help or to talk with others, we encourage you to post on the US-RSE slack or write an issue here.
We have a special header field that you can define if you want a page to redirect
elsewhere. We do this by way of a meta tag, and we give the viewer 2 seconds
to see a message that they are being redirected. To keep these pages
organized, we have them located in the redirects folder:
$ ls pages/redirects/
2020-april-workshop.md
And the header front end matter should look like the following:
---
layout: page
title: US-RSE Community Building Workshop
permalink: /2020-april-workshop/
redirect: https://us-rse.org/first-community-workshop
---The above says that the page titled "US-RSE Community Building Workshop" served at permalink /2020-april-workshop will be redirected to https://us-rse.org/first-community-workshop.
If you have a YouTube video to embed, we have an include that will make it easy to embed a full width, fullscreen enabled video! Simply do:
{% include youtube-embed.html url="https://www.youtube.com/embed/gP5UCfV3n-A" title="Video Title" %}
Where the url should be the embed URL that is provided to you when you click to share and then embed (note that "embed" is in the url) and the title is a title of your choosing. You are not required to include a title, and it will default to a generic "YouTube video player."
Tests are run during continuous integration to catch any errors and to preview content. Specifically, usrse.github.io uses the following integrations (with links to configuration files):
- CircleCI previews the site, and tests jobs and mapdata
- GitHub CI includes GitHub triggers and actions
Instructions for running locally, along with details about each, are provided below.
CircleCI is the primary means to preview a pull request, as the site is built and available for preview as an artifact. Additionally, the jobs and map data is tested (details below). There are no credentials or secrets required for this setup, other than the repository needing to be connected to CircleCI, and under settings:
- build forked pull requests should be on
- cancel redundant builds is suggested
- workflows should be enabled
If you want to edit any of the tests, you should edit config.yml. Details about running tests locally are included below. This can be good to do if you change an input file in _data and want to test it.
Jobs are tested for correctness, meaning that all fields are entered, a date string is entered for the "expires" field, and the url is valid. You can run tests locally like:
$ cd tests
$ python -m unittest test_jobsA script is provided that will clone the repository to a temporary directory, find all commits with a changed job file, and then checkout and read each commit to get the jobs present for that time. We then use the title and url for the job as a unique identifier to determine if the job has been seen. A job with the same name and url, and thus the same unique identifier, is considered the same job. You can run this script as is if you just want to derive counts:
$ python scripts/count_jobs.py
Cloning repository https://github.com/USRSE/usrse.github.io
Found 43 commits for _data/jobs.yml
Found a total of 35 unique jobs across 43 commits.or you can add an output file to save the compiled job content to file
$ python scripts/count_jobs.py all-jobs.yml
Cloning repository https://github.com/USRSE/usrse.github.io
Found 43 commits for _data/jobs.yml
Found a total of 35 unique jobs across 43 commits.
Saving to output file /home/vanessa/Desktop/Code/usrse/usrse.github.io/all-jobs.ymlThe repository is always cleaned up, and the parsing done separately from the script.
To preview the site on CircleCI, after it finishes building, make sure you are logged in and following the repository, and then click on the "Artifacts" tab. You can select the static file to open and preview in your browser.
To preview the site locally, you'll need to install jekyll It's then typical to go to the root of the site and issue (just once):
$ bundle installAnd then (also in the top level directory of your forked repository) run
$ jekyll serve
# or
$ bundle exec jekyll serveand open your browser to http://localhost:4000.
If you are having trouble try rm -rf _site, followed by bundle update, then bundle exec jekyll serve.
A legacy Rakefile is kept with the repository to allow for a manual rake test
to use the html-proofer to check links.
This was previously deployed on TravisCI, however it was very buggy and failed often since the checker had no concept of retry. While the travis instruction has since been removed, you can look at the old configuration file here in a previous commit. To run this previous test locally on your own you can do:
$ rake testThis has been replaced by the "URLChecker" in GitHub CI, which does have retry and other nice features to make it less error prone, discussed next.
The URLschecker is a GitHub action that @vsoch worked on to contribute retry and some other nice features for the repository here. These features are available as of version 0.1.6 that is used in the workflow.
The workflow clean-expired-jobs.yml is run nightly, and uses the same function from the urlchecker to check for expired links in jobs.yml, and given an expired link, remove it from the file if the url check fails. In the case that a link is not expired and the check fails, we would want to know about this (and the test will fail).
This simple greetings action greets first time users (for issues). The logic of this is determined by the greetings.yml workflow.
Two scripts help to create a branch with an updated member counts file
that starts with the prefix update/member-counts. The workflow member-counts.yaml will generate an updated file and commit and push to a new branch, and it uses pull-request.sh to then open a PR with the new branch to the repository. For GitHub CI, there are currently no secrets or credentials, and no setup is required - having actions enabled for the repository and placing the file under .github/workflows
enables it.
Why do we use different services?
Using multiple "free tier" CI services is a common thing for open source projects to do. There are several reasons to do this:
- we can better leverage a free tier, meaning a maximum number of jobs run in parallel or minutes per month by spreading work over multiple services.
- we can scope a particular kind of test to a service. For example, one service might just be to test the core software, another might be to build and deploy containers, and a third might be to preview a site.
- each CI service offers unique features. For example, GitHub has the closest integration with the repository here, and CircleCI allows us to preview artifacts.
We use the all-contributors tool to generate a contributors graphic below.
