Programming Languages Reading Group

The Augusta University Programming Languages Reading Group is a regular meeting to discuss recent results in programming languages (PL) research. The intent of the group is to learn about various ideas and generally broaden perspectives on PL research. Each week, members vote on a selection of papers drawn at random from top PL conferences. We gather in person weekly to discuss the selected papers. This repository contains our website and the tooling we use to select papers. The PL Reading Group is organized by the ΔΛΔ student organization.

Quick start

1. Populate data/sources.csv with your favorite venues.
2. Execute npm run update to fetch papers from those venues.
3. Commit these changes to the repository.
4. Enable one of the workflows for automatic paper selection.

Everyday use

Common commands

Command	Effect
npm run choose [-- n]	select n papers randomly from the dataset
npm run details -- <DOI>	look up title and citation of the paper with given DOI
npm run set -- <DOI>	manually set the next paper
npm run stats	print statistics about the dataset
npm run update	update the dataset

Setting sources for paper selection

The file data/sources.csv contains a list of conferences, one per line, from which papers are selected. After modifying this file you must update the dataset for the changes to take effect.

Each line of data/sources.csv contains the name and year of a conference separated by a comma, and with no additional whitespace. The name is such that the following URL is valid on DBLP.

https://dblp.org/db/conf/<name>/index.html

You can use this to discover conferences by browsing DBLP.

Notes.

• Venues other than conferences (e.g. journals) are not supported at the moment.
• This software identifies papers by their DOI, so conferences that do not register DOIs for their papers are not supported.

Filtering papers by keywords

Each line of the file data/stopwords.txt contains a keywords to exclude during the selection process. Any paper whose title contains (case-insensitively) any of the keywords will not be suggested for reading.

Updating the dataset

To update the dataset, run npm run update. This operation uses the existing dataset as a cache to minimize API calls. If you want to rebuild the dataset from scratch, delete the file data/papers.json. By default, papers from venues (and years) no longer listed in data/sources.csv will be removed during the update. This behavior may be changed by editing the DATASET.KEEP_OLD_PAPERS option.

Troubleshooting. If calls to the DBLP API fail, you can inspect the relevant URLs by running npm run venues.

Getting the next paper suggestion

The paper selection actions run on a schedule, but can also be triggered manually by running the configured workflow in GitHub actions. Doing so will generate PRs with paper suggestions. Only those with the appropriate repository permissions may run these workflows manually.

Both workflows invoke npm run choose and npm run set in the background. The command npm run choose takes an optional numerical parameter n, the number of papers that should be selected. If no parameter is given, it defaults to 1. This command prints prints the selected papers, and writes an array containing their DOIs to the file data/choices.json. Other than that, it does not modify the repository. The choices are made according to the RANDOM_POLICY option.

Manually setting the next paper

Manually run the set paper workflow with the desired paper's DOI as input. If the DOI does not correspond to any paper in the dataset, information about the paper will be retrieved from the internet and added to the dataset.

The corresponding command is npm run set -- <DOI>. This command also modifies the website files, history, etc.

Configuration file

The file src/config.ts contains various settings for the runtime behavior of the paper selection script. The effects of individual configuration options are described in the comments of that file.

Semester maintenance

Light maintenance is needed between semesters/reading periods.

Start of semester

1. Archive the previous semester: Run the script to archive the most recent semester

   bash archive_semester.sh <SEMESTER> <YEAR>

   For example archive_semester.sh fall 2025. This script will create a new directory in docs/_past_semesters, copy the reading group info for the past semester to that directory and clear the automatically generated files in docs/.

2. Clear the Schedule: Edit the schedule (the table at the bottom of docs/index.md). Adjust dates, locations etc. as appropriate. Fill the description colum with a placeholder. By default you should use

   Paper <number> discussion
   

   If you wish to use a different placeholder, customize the variable SCHEDULE_PLACEHOLDER_RE to a regular expression which matches your placeholder (and no other part of index.md).

3. Edit readme.md to reflect information about the new semester.

4. Enable one of the paper selection workflows.

End of semester

Disable the configured workflow.

Editing

Development commands

Command	Effect
npm install	Install development dependencies
npm run build	Typecheck the source code
npm run serve	Run Jekyll for Website development
npm run venues	Print URLs for debugging DBLP requests

Editing the source code

To execute the source code, Node.js version 22.6.0 or greater is required. This version added native typescript execution.

To work on the source code, you will need:

• the typescript compiler
• type declarations for nodejs
• (optional) the typescript language server

Running npm install will install all of the above locally in your development directory.

Editing the website

Basic edits to the website can be performed by editing the markdown files in the docs/ directory. For more comprehensive edits, follow the instructions at website development.

Editing the blog

Blog posts are ordinary markdown files located in the docs/_posts directory. Their file names are formatted as YYYY-MM-DD-<short title>.md, where the former part is the date of the blog post. A template for authoring new posts is provided at docs/_posts/template.md.

Website development

The docs/ directory contains files for the PL Reading Group website. It is build using Jekyll and markdown. Substantial edits to the website should be prototyped locally, which requires Ruby and Jekyll. To install dependencies and get started with local development, follow these instructions:

1. Install Jekyll
2. cd docs/.
3. Install dependencies: bundle install
4. Run the website locally: bundle exec jekyll serve or cd .. && npm run serve
5. Preview the website on localhost:4000/plgroup.

Using the workflows

There are two available workflows: ranked choice voting and reviewer approval. Only one workflow should be enabled during a semester/reading period. Workflows are controlled by variables which can be managed at settings > secrets and variables > actions (variables)

Workflow scheduling

The paper-selection actions run on automated schedule. To change the schedule, refer to the documentation on workflow schedules.

Workflow I: ranked choice voting

This workflow generates a predefined number of 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.

• Set DISCORD_WEBHOOK_URL secret to direct to the intended discord channel.
• Set PAPER_VOTE_ON variable to 1 to enable voting, or 0 to disable.
• Set OPTIONS to the number of options you want to select, e.g. 3 means three options.

Workflow II: participants suggest papers

This workflow functions as ranked choice voting above, but instead of suggesting random papers from the dataset, the vote options are suggested by the reading group participants.

To suggest papers, write their DOIs (one per line) to the file suggestions.txt. This workflow runs automatically when suggestions.txt is modified, and creates a vote option and PR for each paper specified in that file.

Set DISCORD_WEBHOOK_URL secret to direct to the intended discord channel. (same as for ranked choice voting)

Workflow III: reviewer approval

This picks one paper at random and suggets it as the next paper. Designated reviewers must approve the suggetion which comes in the form of PR. Once a sufficient number of reviewers accept the suggestion, the PR is merged. Closing the PR without approval automatically generates a new suggestion. This process repeats until a satisfactory suggestion has been found. The relevant GitHub actions is "Random paper".

• Create a branch protection rule for main branch, to enforce reviewer approval of a paper suggestion, in settings > branches.
  • Check "Require a pull request before merging".
  • Set "Require approvals" count to the minimum number of reviewer required to approve paper suggestion.
• Set REVIEWERS variable to a newline-separated string of GitHub usernames.
  • For example: user1 \n user2 \n user3
  • The users must have sufficient permissions to perform PR reviews.
• Set PAPER_CHOOSE_ON variable to 1 to enable automatic suggestions.
• Set AUTOMERGE_PAT secret to a personal access token of a user with repository write access, to enable auto-merging approved PRs.
  • Permission scopes for classic token: repo
  • Permission scopes for fine-grained token: pull requests write and contents write.
• (Optional) Set DISCORD_WEBHOOK_URL secret to a Discord channel URL to enable notifications.

Initial setup for forked repositories

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 and OPTIONS and OPTION_COUNT
• Configure a paper selection workflow as described above to enable automated paper suggestions.