Add instructions for contributing TILs

README.md

@@ -5,7 +5,7 @@ This repo contains TILs from the team at the [Jean Golding Institute](https://ww
 > [!TIP]  
 > TIL stands for "today I learned". We constantly learn new things that would be useful for others (including our future self!) to see.
 
-[We welcome contributions](#contributing) from the community.
+[We welcome contributions](#contributing-tils) from the community.
 
 TILs are public domain ([CC0](LICENSE)) unless otherwise noted. Any referenced content may have its own license.
 

_contributing-TILs/_how-to-contribute.md

@@ -0,0 +1,26 @@
+# How to contribute a TIL
+
+> [!TIP]  
+> TIL stands for "today I learned". We constantly learn new things that would be for others (including our future self!) to see.
+
+TILs are short markdown files that live inside a directory named after the topic of the TIL.
+
+For first-time contributors, it is recommended that you use the GitHub web interface to add new TILs, which avoids pulling/pushing and the potential for merge conflicts. If you will be editing locally, see the advice on [avoiding conflicts](avoiding-conflicts.md). 
+
+The title of the TIL should be a short, descriptive phrase that summarises the content of the TIL. The title should be a level 1 heading on the very first line of the TIL. For example:
+
+```markdown
+# This is the heading
+
+This is the text of the TIL...
+```
+
+Feel free to include code snippets, links to resources, or any other information that you think would be useful to someone else.
+
+Don't worry about including your name or a date, we can get this from the Git history.
+
+After creating a TIL, commit and push your changes back to GitHub. If you have push access to this repo, then that's all you'll need to do. If you are an external collaborator (we thank you for contribution!) then you'll need to create a pull request.
+
+Your contribution will be considered public domain ([CC0](LICENSE)) unless otherwise noted. Any referenced content may have its own license.
+
+After you push to the repo (or your pull request is merged), a [GitHub Action](/.github/workflows/build.yml) will automatically add your TIL, along with the date it was created, to the [`README.md`](/README.md) for this repo.

_contributing-TILs/avoiding-conflicts.md

@@ -0,0 +1,20 @@
+# How to push/pull without conflicts
+
+Because a [GitHub Action](/.github/workflows/build.yml) runs and adds commits to the repo, you will probably find that you can't push to the repo without first pulling the changes.
+
+> [!TIP]  
+> Remember to pull from GitHub before you make any changes or commits. You should also avoid committing changes to the [`README.md`](/README.md) file, as this will get updated automatically by GitHub Actions and if you update it too then you can easily get merge conflicts.
+
+If you are editing locally and forget to pull from GitHub before making a commit, then you can subsequently pull changes from GitHub, asking for Git to rebase your changes onto the newly pulled commits. Then you can push your changes to GitHub. If you also have [previewed what the `README.md` will look like](preview-README.md) after the GitHub Action has run, you should discard those changes first.
+
+The commands will look similar to the following:
+
+```bash
+git add my-topic/my-new-TIL.md
+git commit -m "Add a TIL about something I learned"
+git restore README.md  # (optional) discard any changes to README.md, if you have changed it
+git pull --rebase
+git push
+```
+
+If you have also committed changes to [`README.md`](/README.md) then this approach won't work and you'll probably get a merge conflict. Don't worry, just edit the file locally to remove the conflict, and make a new commit to merge the 'branches' back together again.

_contributing-TILs/prevent-GitHub-actions.md

@@ -0,0 +1,5 @@
+# How to commit and push without GitHub Actions from running
+
+Add the text `[skip ci]` to your commit message.
+
+Via: https://github.blog/changelog/2021-02-08-github-actions-skip-pull-request-and-push-workflows-with-skip-ci/

_contributing-TILs/preview-README.md

@@ -0,0 +1,36 @@
+# How to preview the `README.md` locally
+
+> [!NOTE]
+> For normal use, you don't need to do this. A [GitHub Action](/.github/workflows/build.yml) will automatically update the `README.md` file when you push changes to the repo.
+>
+> Also bear in mind that you probably don't want to commit changes to the [`README.md`](/README.md), unless you are updating some of the the parts outside the placeholder tags. Otherwise you will likely get merge conflicts. See below for how to discard changes to the file before pulling.
+
+To build the [`README.md`](/README.md) file locally, you will need to create and activate a virtual environment using Python 3.12+, and then install the dependencies for this project.
+
+For Mac/Linux:
+
+```bash
+python3.12 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+For Windows:
+
+```cmd
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+You can then run the `generate_readme.py` script to see what the new [`README.md`](/README.md) file will look like.
+
+```bash
+python generate_readme.py
+```
+
+It might be helpful to discard uncommitted changes to the [`README.md`](/README.md) file before pulling from GitHub, to avoid merge conflicts. You can do this with the following command:
+
+```bash
+git restore README.md
+```