This repository contains tooling for our programming languages reading group.

Augusta University Programming Languages (PL) Reading Group is a regular meeting to discuss exciting recent results in programming languages research. The intent of the group is to learn about various ideas and generally broaden perspectives on PL research topics. We select papers randomly from top programming languages conferences, with final selection made by ranked choice voting by reading group members. We gather weekly in person to discuss the selected papers. This repository contains a small website and tooling to assist in selecting papers to read.

Available commands

Running these commands requires Node.js.

npm run update             : update paper dataset
npm run stats              : display paper dataset statistics
npm run choose             : choose next paper
npm run web                : auto-update web page 
npm run set -- [doi]       : manually set the next paper
npm run details -- [doi]   : print meta data about a paper

This section describes to how to apply the most commonly expected changes.

How to edit source conferences?

The conference sources are in sources.txt, one per line. Change these sources, then run npm run update to regenerate a dataset of papers. This process will take up to a few minutes, depending on the number of new papers. The update is additive. To remove older entries, first delete data/papers.json.

How to filter papers by specific keywords?

"Stopwords" is a list of keywords where, if any of them appear in the paper title, that paper is not considered for selection. Edit this list by changing stopwords.txt. Each line is considered a separate stop word, and paper is evaluated against each word in this list (case-insensitive match).

How to change the website content?

Edit files in docs written in markdown. The website theme is from here. You can override desired parts and customize the site following Jekyll docs. For more comprehensive edits, or to debug build issues, follow the instructions for website development.

How to get a suggestion for the next paper?

The paper-selection actions run on automated schedule, but paper selection can be dispatched manually if needed. Run the "random paper" action or "vote open" action, in actions, depending on the configured workflow. The option to dispatch an action is available based on repository permissions. Running a paper-selection action will generate appropriate PRs with paper suggestions.

How to set the next paper (bypassing randomness)?

Manually run the "set paper" workflow with a DOI as a parameter. The workflow will run all necessary updates and generates a PR of changes. Approve the PR to confirm the next paper.

How to change the paper selection schedule

The paper-selection actions run on automated schedule. To change the schedule, follow these instructions.

Light maintenance is needed between semesters/reading periods to boot and shutdown the automated actions.

1. Update semester docs

   Set values for SEM and YEAR variables to the most recently concluded semester. Then, run the command to archive the corresponding semester. It archives the appropriate files and initializes a new semester.

   SEM=fall && YEAR=2023 \
   && DOCS=docs/ && DATA=data/ \
   && OLD_DIR=$DOCS"_past_semesters/"$YEAR"_"$SEM \
   && mkdir -p $OLD_DIR \
   && cp $DOCS"index.md" $OLD_DIR"/index.md" \
   && mv $DOCS"papers.md" $OLD_DIR"/papers.md" \
   && [ ! -f $DOCS"awards.md" ] || mv $DOCS"awards.md" $OLD_DIR"/awards.md" \
   && echo -n '' > $DATA"/past.txt" \
   && echo -n '' > $DATA"/next.txt" \
   && touch $DOCS"awards.md" \
   && touch $DOCS"papers.md"

   Edit docs/index.md to describe the current or upcoming semester.

2. Turn on paper selection workflow in settings > secrets and variables > actions:

   • For reviewer approval, set PAPER_CHOOSE_ON value to 1
   • For ranked choice voting, set PAPER_VOTE_ON value to 1

1. Turn off paper selection workflows in settings > secrets and variables > actions:
   Set PAPER_CHOOSE_ON and PAPER_VOTE_ON values to 0.

Pause or restart the workflows as necessary, by toggling the paper section workflows in repository settings.

• To pause: set PAPER_CHOOSE_ON and PAPER_VOTE_ON values to 0.
• To restart: set PAPER_CHOOSE_ON or PAPER_VOTE_ON value to 1, based on configured paper-section workflow.

The docs/ directory contains documents for the PL Reading Group website. It is build using Jekyll and markdown. Local development requires Ruby, Jekyll, and various Ruby gems. Follow these steps for local setup.

1. Install Jekyll then cd docs/.
2. Install dependencies: bundle install
3. Run the website locally: bundle exec jekyll serve

The repository code is generic in the sense that, by changing the conference sources.txt, it can be made to suggest any kinds of papers that have DOIs indexed by Crossref. Complete the following steps to activate the automated actions.

• Enable workflow permissions in settings > actions > general:
  • choose "Read and write permissions"
  • check "Allow GitHub Actions to create and approve pull requests
• Create environment secrets and variables, with empty default values, in settings > secrets and variables > actions:
  • secrets: DISCORD_WEBHOOK_URL and AUTOMERGE_PAT
  • variables: PAPER_CHOOSE_ON and PAPER_VOTE_ON and REVIEWERS
• Configure a paper selection workflow to enable automated paper suggestions.

There are two available workflows: ranked choice voting and reviewer approval. One workflow should be enabled during a semester/reading period.

This workflow generates four random paper suggestions. Those suggestions are then posted to a Discord channel for voting by channel members. A corresponding PR is generated for each paper suggestion. The vote is concluded manually by merging the winning suggestion PR. The remaining PRs will be closed/discarded automatically. The relevant GitHub actions are "Vote open" and "Vote close". This workflow requires Discord integration to conduct voting.

Ranked choice voting generates multiple paper suggestions and readers vote for a winner.

This workflow chooses randomly one paper suggestion and designated reviewers must approve the PR. Once a sufficient number of reviewers accept the suggestion, the PR is merged. Closing a suggestion without approval automatically generates a new suggestion. This process repeats until a satisfactory suggestion has been found. The relevant GitHub actions is "Random paper".

Random paper suggestion generates one paper suggestion for reviewers to approve.