Skip to content

Commit

Permalink
Sam's attempt at a welcoming CONTRIBUTING file. (#278)
Browse files Browse the repository at this point in the history 
> [!NOTE] 
> Reviewers:
> Please do double-check that what I've written doesn't break the flow
of README.md and that I've kept the tone encouraging.

* Solves (the rest of?) #245 
* Supersedes #252 (although as I write this comment, I realise there're
significantly fewer ❤️ emoji).

---------

Co-authored-by: Matt Graham <matthew.m.graham@gmail.com>
  • Loading branch information
@samcunliffe @matt-graham
samcunliffe and matt-graham authored Jan 23, 2024
1 parent d650dc1 commit 14bd74b
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 50 deletions.
39 changes: 39 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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 -->
104 changes: 54 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 -->

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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 .
Expand All @@ -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>

0 comments on commit 14bd74b

Please sign in to comment.