Skip to content

Commit

Permalink
Good suggestions from PR.
Browse files Browse the repository at this point in the history
  • Loading branch information
@samcunliffe
samcunliffe committed Jan 23, 2024
1 parent c0ad04c commit d6e33f6
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 26 deletions.
17 changes: 9 additions & 8 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
This template and our [recommendation pages][website] were made by [RSE]s 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!
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?
Expand All @@ -16,13 +16,13 @@ put you off creating an issue.

To contribute a change, please:

1. Create a new branch (or fork if you're not in ARC-collaborations).
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 ARC-collaborations to
review it.
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.
Expand All @@ -34,5 +34,6 @@ To contribute a change, please:
[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
[RSE]: https://society-rse.org/about/history
[Research software engineers]: https://society-rse.org/about/history
[@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations
<!-- prettier-ignore-end -->
62 changes: 44 additions & 18 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,11 +97,17 @@ pip install cookiecutter

## Notes for developers

<details>
<summary>Click to expand...</summary>

First, clone repository

- (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:
- (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
Expand All @@ -107,7 +126,8 @@ cd python-tooling
```

- 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 @@ -130,13 +150,19 @@ cd python-tooling

### Developing the recommended tooling pages

Edit the files in [./docs/pages]. They are standard markdown so they're viewable
here in the repo as well as when deployed as a web page.
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)

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.
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.

</details>

0 comments on commit d6e33f6

Please sign in to comment.