Merge branch 'main' into github_readers

README.md

@@ -66,9 +66,9 @@ pre-commit install
     source .env
     ```
 
-1. Run the bot:
+1. Run the bot using [`slack_bot/run.py`](https://github.com/alan-turing-institute/reginald/blob/main/slack_bot/run.py). To see CLI arguments:
     ```bash
-    python slack_bot/bot.py
+    python slack_bot/run.py --help
     ```
 
 The bot will now listen for @mentions in the channels it's added to and respond with a simple message.

azure/setup.sh

@@ -125,7 +125,7 @@ if [ -z "$LLAMA_SLACK_BOT_TOKEN" ]; then
 fi
 AZURE_KEYVAULT_AUTH_VIA_CLI=true pulumi config set --secret LLAMA_SLACK_BOT_TOKEN "$LLAMA_SLACK_BOT_TOKEN"
 
-# The ChatCompletionAzure and LlamaGPT35TurboAzure models need an Azure backend
+# The ChatCompletionAzure and LlamaGPTAzure models need an Azure backend
 if [[ $REGINALD_MODEL == *azure* ]]; then
     if [ -z "$OPENAI_AZURE_API_BASE" ]; then
         echo "Please provide a OPENAI_AZURE_API_BASE:"
@@ -139,7 +139,7 @@ if [[ $REGINALD_MODEL == *azure* ]]; then
     AZURE_KEYVAULT_AUTH_VIA_CLI=true pulumi config set --secret OPENAI_AZURE_API_KEY "$OPENAI_AZURE_API_KEY"
 fi
 
-# The ChatCompletionOpenAI and LlamaGPT35TurboOpenAI models need an OpenAI key
+# The ChatCompletionOpenAI and LlamaGPTOpenAI models need an OpenAI key
 if [[ $REGINALD_MODEL == *openai* ]]; then
     if [ -z "$OPENAI_API_KEY" ]; then
         echo "Please provide a OPENAI_API_KEY:"

data/public/handbook_raw_mds/advanced.md

@@ -0,0 +1,49 @@
+---
+# Page title as it appears in the navigation menu
+title: "Advanced"
+# Adjust weight to reorder menu items (lower numbers appear first)
+weight: 7
+# Uncomment to hide nested pages in a collapsed menu
+# bookCollapseSection = true
+# Uncomment to hide this page from the navigation menu
+# bookHidden = false
+# Uncomment to exclude this page from the search
+# bookSearchExclude = true
+---
+
+# Advanced
+
+## Using Data
+
+Through using templates Hugo can [build page content from
+datafiles](https://gohugo.io/templates/data-templates/). This is particularly
+useful for when you want to display structured data in a page and when it would
+be easier to maintain a datafile rather than a Markdown or HTML document.
+
+## Creating Shortcodes
+
+It is possible to [create your own
+shortcodes](https://gohugo.io/templates/shortcode-templates/). These should be
+placed in {{% repo_link path="layouts/shortcodes/" text="`layouts/shortcodes/`"
+%}}.
+
+If you feel the need to use HTML or want to create page content from a datafile
+(like a YAML file or csv) then a shortcode is probably the right answer.
+
+You should refer to Hugo's [templates](https://gohugo.io/templates/) and
+[functions](https://gohugo.io/functions/) documentation for resources to help
+writing a shortcode.
+
+## Partial Templates
+
+Whole page templates are built from of a number of smaller [partial
+templates](https://gohugo.io/templates/partials/). This approach reduces
+repeated code in templates and help keep making changes simple.
+
+The theme defines a number of dummy [partial
+templates](https://github.com/alex-shpak/hugo-book#partials) for us to
+overwrite.
+
+For example, the Creative Commons notice at the bottom of each page was added by
+editing {{% repo_link path="layouts/partials/docs/inject/footer.html"
+text="`layouts/partial/docs/inject/footer.html`" %}}.

data/public/handbook_raw_mds/buddy_system.md

@@ -0,0 +1,64 @@
+---
+# Page title as it appears in the navigation menu
+title: "Buddy System"
+# Adjust weight to reorder menu items (lower numbers appear first)
+weight: 1
+# Uncomment to hide nested pages in a collapsed menu
+# bookCollapseSection = true
+# Uncomment to hide this page from the navigation menu
+# bookHidden = false
+# Uncomment to exclude this page from the search
+# bookSearchExclude = true
+---
+
+# Buddy System
+
+It can be daunting starting a new job, especially remotely where there is sometimes less opportunity for casual questions.
+To help with this every new employee should be assigned buddies.
+The buddies are responsible for providing informal friendly faces to offer advice, guidance, and encouragement on any aspect of working within REG and ARC.
+
+We also emphasise that the buddies should be a safe space where new-starters can get help with any technical questions that they feel is silly or trivially easy and may not feel comfortable admitting to the wider group.
+
+## The Process
+
+Before the new starter starts at the Turing they should be assigned **two buddies** from our [buddy pool](https://github.com/alan-turing-institute/research-engineering-group/wiki/Buddy-Sign-up-and-Matches).
+If possible, the buddies should not be assigned to the projects on which the new starter is likely to work, and ideally at a similarly seniority to the new starter.
+
+We would also like for each new starter to have a third buddy from some other team.
+We think that in a remote & hybrid setting it will help new-starters meet people and get a feel for the wider Turing ecosystem.
+This has been trialed in a few instances, to positive feedback, but to make this be standard practice we would need it to be more bidirectional, with REGers volunteering to buddy with people outside of REG.
+
+The new-starter should be made aware of the buddies' role before they start, and meeting their buddies should typically be the first appointment on their first day.
+
+The buddy system in managed by
+[the person in charge of onboarding](https://github.com/alan-turing-institute/research-engineering-group/wiki/The-REGistry#responsibilities).
+
+## Buddy Guidelines
+
+- Have a coffee with the new employee on their first day.
+- If needed, introduce them to the team at welcome coffee.
+- Be as informal as possible, make the new starter feel welcome and comfortable.
+- Make sure the new starter is familiar with the [New Starter page]({{< relref "/docs/onboarding/new_joiners" >}}). Check for sticking points.
+- Meet the new starter where they are at.
+- Make it clear that the new employee can get in touch any time for questions and concerns, regardless of triviality.
+- Emphasise that you're also there for technical pointers. This is to encourage the new-starter to be comfortable asking for help when they are stuck and hopefully lessening imposter syndrome anxiety.
+- Have a check-in chat with the new starter at least once in the first couple of weeks, and again a few weeks after. During these check-ins, uncover pain points and concerns.
+- Help socialise the new employee to the group's culture and processes.
+- Be open, honest, and respect confidentiality.
+- If needed, help make introductions.
+
+## Tips for Buddies
+
+- Don’t worry about being perceived as the expert. Focus your attention on the new employee.
+- Be patient: It takes time to develop a relationship. Don’t try to cover everything right away.
+- Be positive: New employees will grow into their roles if given proper reinforcement.
+- Don’t try to force a relationship. New employees will vary in how much they turn to a buddy.
+- Try to identify the new employee’s personality and communication style and adapt accordingly.
+- Don’t be judgemental. Simply offer feedback.
+- Maintain a good attitude and a teaching spirit.
+
+## How to be a Buddy
+
+Being a buddy can be a rewarding process.
+You will help avoid new starters feeling at sea and reaffirm their decision to join the group.
+To sign up please add your name to our [buddy pool](https://github.com/alan-turing-institute/research-engineering-group/wiki/Buddy-Sign-up-and-Matches).

data/public/handbook_raw_mds/change_logs.md

@@ -0,0 +1,19 @@
+---
+# Page title as it appears in the navigation menu
+title: "Changelogs and Semantic Versioning"
+# Adjust weight to reorder menu items (lower numbers appear first)
+weight: 2
+---
+
+# Changelogs
+
+For any non-trivial code, it is worth maintaining a Changelog.
+This is valuable as it is a record of changes _from the perspective of users_ (rather than git commit messages which are often only meaningful to the developers involved).
+A recommended format for Changelog files is given at [Keep a changelog](https://keepachangelog.com).
+All notable changes to a project should be documented in this file.
+
+## Semantic Versioning
+
+A related concept is [semantic versioning](https://semver.org/spec/v2.0.0.html).
+In most cases, semantic versioning is recommended.
+You should state explicitly whether or not you are using semantic versioning in both your project's README and CHANGELOG files.

data/public/handbook_raw_mds/code_audits.md

@@ -0,0 +1,45 @@
+---
+# Page title as it appears in the navigation menu
+title: "Repo Audits"
+# Adjust the weight to reorder menu items (lower numbers appear first)
+weight: 2
+# bookCollapseSection = true
+# Uncomment to hide this page from the navigation menu
+# bookHidden = false
+# Uncomment to exclude this page from the search
+# bookSearchExclude = true
+---
+
+# Repo Audits
+
+As required we conduct audits of GitHub repositories created during projects.
+The aim is to check that the documentation is clear, installation is easy etc.
+
+Audits should be conducted by people who have not worked on the project.
+
+## Past experience
+
+These comments from running the first round of these in June 2021:
+
+> Installation is a big barrier for software with complex build requirements.
+> We tried looking at two web app projects (Counterfactual Covid 19 and CROP) and despite Docker images being available we weren't able to get them to build correctly.
+> We might have had more success if all we needed to do was a pip or CRAN install.
+>
+> - First lesson: installation is ALWAYS harder than you think, and we need to get more fresh eyes on build instructions if we want our software to be easily usable.
+> - Second Lesson: Not having someone on hand from the project can be a big barrier, as we suspect there may have just been some small tweaks or changes that would fix our problem.
+> - One suggestion was to have a mix of unsupervised hacking and more knowledgeable feedback, maybe by having the person working on the project show up an hour in. If we can't get someone who knows the project well to attend, at least have them available on Slack in case we get stuck.
+> - At the very least, we were able to document our issues on the repo, and in at least one case the project was able to make fixes.
+>
+> One suggestion is to encourage "Good First Issue" tags or "Hacktoberfest"-type tags that would help people know what simple things could be tackled in a few hours if they succeed in installing the software.
+> I have found that it isn't always straightforward to come up with such issues (I tried thinking of some for a previous iteration of the activity, but always got stuck when I realized I didn't have a clue what to do and explaining the problem was hard enough), and in projects that are currently running it isn't always easy to leave these uncompleted when you have more time to work on a project.
+>
+> One idea was to have a HackMD document, similar to the one that suggests project meetings for new joiners to shadow, that lists all repos with such issues in one place, making it easier to find something fruitful to work on if these audits continue to be spontaneous.
+>
+> An alternative is to make these non-spontaneous and schedule them in advance.
+> We've kicked around the thought of scheduling lightning talks for all projects — perhaps we could better leverage people's brains if we gave a lightning talk intro on Tuesday and then guided people through installing and hacking on the software the next day?
+>
+> New joiners to projects inevitably spend a bunch of time doing exactly what we were trying to do in these sessions.
+> Can we leverage the time investment of the new joiner by doubling up other team members to do this?
+>
+> Should new joiners to the team be encouraged to do this for a couple of weeks before being assigned to a project?
+> I had a few new joiners on one of the audit sessions, and they said it was a good way to learn more about the team and our projects.

data/public/handbook_raw_mds/coffee_chats.md

@@ -0,0 +1,18 @@
+---
+# Page title as it appears in the navigation menu
+title: "Coffee Chats"
+# Adjust weight to reorder menu items (lower numbers appear first)
+weight: 1
+# Uncomment to hide nested pages in a collapsed menu
+# bookCollapseSection = true
+# Uncomment to hide this page from the navigation menu
+# bookHidden = false
+# Uncomment to exlude this page from the search
+# bookSearchExclude = true
+---
+
+# Coffee Chats
+
+The team has two optional, daily coffee chats at 08:45 and 13:45.
+The chats usually happen in Gather but there is also a Zoom room in case Gather is unavailable.
+Details for both rooms can be found [here](https://github.com/alan-turing-institute/research-engineering-group/wiki/The-REGistry#video-call-links).