Sam's attempt at a welcoming CONTRIBUTING file.

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+This template and our [recommendation pages][website] were made by [research
+software engineers] at [UCL's Centre for Advanced Research Computing][UCL ARC].
+We made it with research software projects in mind, but whoever you are, we hope
+you find this useful!
+
+We are actively encouraging users to ask questions and start discussions in the
+[discussions tab] of this repository. Does something seem like it's broken?
+Please go ahead and [open an issue]!
+
+The [website] pages are open to contributions but they will need to be reviewed
+by a member or associate member of ARC. We might be slow to approve new tool
+suggestions (since we'll probably want to discuss them first) but don't let that
+put you off creating an issue.
+
+## Development workflow
+
+To contribute a change, please:
+
+1. Create a new branch (or fork if you're not in [@UCL-ARC/collaborations]).
+2. Modify an existing page, create a new one, or tweak the template.
+   a. Run [pre-commit](https://pre-commit.com) which will lint your changes.
+   b. Check the tests pass if you modified the template (`pytest -s`).
+3. Open a _pull request_ (PR) with changes.
+4. Ask someone who did not contribute to the PR from [@UCL-ARC/collaborations]
+   to review it.
+5. If approved with no comments, then the reviewer will merge the PR.
+6. If changes are requested, the PR author should address the comments, and then
+   ask for review again.
+
+<!-- links here -->
+
+<!-- prettier-ignore-start -->
+[website]: https://github-pages.arc.ucl.ac.uk/python-tooling
+[UCL ARC]: https://ucl.ac.uk/arc
+[open an issue]: https://github.com/UCL-ARC/python-tooling/issues/new/choose
+[Discussions tab]: https://github.com/UCL-ARC/python-tooling/discussions
+[Research software engineers]: https://society-rse.org/about/history
+[@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations
+<!-- prettier-ignore-end -->

README.md

@@ -1,13 +1,20 @@
 # UCL ARC Python Recommendations
 
-This repository collects the [UCL ARC] recommendations for a Research Software project in Python.
-It contains a template for new Python packages and a [website] documenting our recommendations.
-We've turned on [discussions](https://github.com/UCL-ARC/python-tooling/discussions) for this repo, and we welcome questions there or in the `#programming-help` channel on the [UCL research software hub slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub).
+This repository collects the [UCL ARC] recommendations for a Research Software
+project in Python. It contains a template for new Python packages and a
+[website] documenting our recommendations. We've turned on
+[discussions](https://github.com/UCL-ARC/python-tooling/discussions) for this
+repo, and we welcome questions there or in the `#programming-help` channel on
+the [UCL research software hub
+slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub).
 
-🍪 Our template is a [cookiecutter] template which automatically creates new Python packages with our recommended tooling set up and ready to go.
+🍪 Our template is a [cookiecutter] template which automatically creates new
+Python packages with our recommended tooling set up and ready to go.
 
 > **Note**
-> If you're making a package within a community that has an existing package template (e.g., [`scikit-hep`](https://github.com/scikit-hep/cookie)), we recommend using their template instead of this one.
+> If you're making a package within a community that has an existing package
+> template (e.g., [`scikit-hep`](https://github.com/scikit-hep/cookie)), we
+> recommend using their template instead of this one.
 
 <!-- links here -->
 
@@ -19,7 +26,8 @@ We've turned on [discussions](https://github.com/UCL-ARC/python-tooling/discussi
 
 ## Using this template
 
-1.  Install [cookiecutter](https://libraries.io/pypi/cookiecutter) in a `conda`, `mamba` or `venv` environment (commented lines for conda example).
+1.  Install [cookiecutter] in a `conda`, `mamba` or `venv` environment
+    (commented lines for conda example).
 
 ```
 # conda create --channel conda-forge --name new-env-name
@@ -32,13 +40,16 @@ pip install cookiecutter
    ```
    cookiecutter gh:ucl-arc/python-tooling
    ```
-   If you have this repo locally (this may be the case if you are developing), you can run the following:
+   If you have this repo locally (this may be the case if you are developing),
+   you can run the following:
    ```
    cookiecutter /path/to/your/checkout/of/python-tooling
    ```
-3. A series of questions will pop up to configure the project. Type the answer or hit return to use the default option (shown in square brackets).
+3. A series of questions will pop up to configure the project. Type the answer
+   or hit return to use the default option (shown in square brackets).
 
-   Note that these project variables are defined in the `cookiecutter.json` file.
+   Note that these project variables are defined in the `cookiecutter.json`
+   file.
 
 4. This will create a specific directory structure.
 
@@ -63,15 +74,17 @@ pip install cookiecutter
        └── test_dummy.py
    ```
 
-   And the `PROJECT_NAME` will appear in the README.md as the human-readable name of the project.
+   And the `PROJECT_NAME` will appear in the README.md as the human-readable
+   name of the project.
 
    ```
    cat PROJECT_SLUG/README.md
    # PROJECT_NAME
    ...
    ```
 
-5. To work on your project, initialise a git repository and _install_ it in editable mode.
+5. To work on your project, initialise a git repository and _install_ it in
+   editable mode.
    ```
    cd PROJECT_SLUG
    git init
@@ -84,36 +97,24 @@ pip install cookiecutter
 
 ## Notes for developers
 
-### Contributing
+<details>
+<summary>Click to expand...</summary>
 
-The [website] and source pages are open to contributions but must be reviewed by a member or associate member of ARC.
-We might be slow to approve new tool suggestions (since we'll probably want to discuss them first), but bug reports (and fixes) are very welcome from anyone!
+First, clone repository
 
-Pages all live in the [docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages) sub-directory, and are written in markdown.
+- (Optional) Generate your SSH keys as suggested
+  [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
+- (Optional) GitHub CLI as suggested
+  [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account?tool=cli)
+- Clone the repository by typing (or copying) the following line in a terminal
+  at your selected path in your machine:
 
-To contribute:
-
-1. Create a new branch (or fork if you're not in ARC-collaborations).
-2. Modify an existing page, create a new one, or tweak the template.
-   a. Run [pre-commit](https://pre-commit.com) which will lint your changes.
-   b. Check the tests pass if you modified the template (`pytest -s`).
-3. Open a pull request with changes.
-4. Someone who did not contribute to the PR should review it.
-5. If approved, the reviewer should merge the PR.
-6. If changes requested, the PR author should address the comments, then ask for review again.
-
-### Development
-
-- Clone repository
+```
+git clone git@github.com:UCL-ARC/python-tooling.git
+cd python-tooling
+```
 
-  - (Optional) Generate your SSH keys as suggested [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
-  - (Optional) GitHub CLI as suggested [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account?tool=cli)
-  - Clone the repository by typing (or copying) the following line in a terminal at your selected path in your machine:
-
-  ```
-  git clone git@github.com:UCL-ARC/python-tooling.git
-  cd python-tooling
-  ```
+### Developing the cookiecutter template
 
 - To create and remove your virtual environment
 
@@ -125,7 +126,8 @@ To contribute:
   ```
 
 - To run template in the same path of this repo.
-  We do a test cookiecut of a dummy package and install it to ensure the template setup works.
+  We do a test cookiecut of a dummy package and install it to ensure the
+  template setup works.
 
   ```
   cookiecutter .
@@ -146,19 +148,21 @@ To contribute:
   pytest -s
   ```
 
-- To commit changes
+### Developing the recommended tooling pages
 
-  ```
-  pre-commit run -a
-  git add .
-  git commit -m 'message issue number (#NN)'
-  git push origin NN-future-branch
-  ```
+Pages all live in the
+[docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages)
+sub-directory, and are written in markdown.
+
+To build the webpage locally (for testing)
 
-- To build the docs locally
+1.  [Install jekyll](https://jekyllrb.com/docs/installation)
+2.  Run `bundle install` from the `docs/` directory of this repository to install dependencies.
+3.  Run `bundle exec jekyll serve` from the root directory of this repository.
+    This should fire up a local web server and tell you its address. By default the
+    server will automatically refresh the HTML pages if any changes are made to the
+    markdown sources.
 
-  1.  [Install jekyll](https://jekyllrb.com/docs/installation)
-  2.  Run `bundle install` from the `docs/` directory of this repository to install dependencies.
-  3.  Run `bundle exec jekyll serve` from the root directory of this repository. This should fire up a local web server and tell you its address. By default the server will automatically refresh the HTML pages if any changes are made to the markdown sources.
+See the [jekyll docs](https://jekyllrb.com/docs) for more info.
 
-  See the [jekyll docs](https://jekyllrb.com/docs) for more info.
+</details>