From 3a5a0ebc06e92e254aa4c95568f770f8c3be2c5f Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 23 Jan 2024 15:50:14 +0000 Subject: [PATCH 1/3] Sam's attempt at a welcoming CONTRIBUTING file. --- CONTRIBUTING.md | 38 +++++++++++++++++++++++++++++++++ README.md | 56 +++++++++++++++---------------------------------- 2 files changed, 55 insertions(+), 39 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ad311098 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,38 @@ +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! + +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 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. Ask someone who did not contribute to the PR from 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. + + + + +[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 +[RSE]: https://society-rse.org/about/history + diff --git a/README.md b/README.md index 49c8c05c..58ebb1cb 100644 --- a/README.md +++ b/README.md @@ -84,36 +84,18 @@ pip install cookiecutter ## Notes for developers -### Contributing +First, clone repository -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! +- (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: -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 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 - - - (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 +``` - ``` - git clone git@github.com:UCL-ARC/python-tooling.git - cd python-tooling - ``` +### Developing the cookiecutter template - To create and remove your virtual environment @@ -146,19 +128,15 @@ 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 - ``` +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. -- To build the docs locally +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. +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. From c0ad04c8890c974cb12cafe48dbd12d00a6c7ed1 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 23 Jan 2024 16:49:31 +0000 Subject: [PATCH 2/3] Suggestions from code review Co-authored-by: Matt Graham --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad311098..6f45218f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ 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 +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 @@ -20,7 +20,7 @@ To contribute a change, please: 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. +3. Open a _pull request_ (PR) with changes. 4. Ask someone who did not contribute to the PR from ARC-collaborations to review it. 5. If approved with no comments, then the reviewer will merge the PR. From d6e33f6f56655e913388b64cc4b841a7e3dcc69a Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 23 Jan 2024 17:00:01 +0000 Subject: [PATCH 3/3] Good suggestions from PR. --- CONTRIBUTING.md | 17 +++++++------- README.md | 62 +++++++++++++++++++++++++++++++++++-------------- 2 files changed, 53 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f45218f..07d4056b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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? @@ -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. @@ -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 diff --git a/README.md b/README.md index 58ebb1cb..ea716cda 100644 --- a/README.md +++ b/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. @@ -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,7 +74,8 @@ 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 @@ -71,7 +83,8 @@ pip install cookiecutter ... ``` -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,11 +97,17 @@ pip install cookiecutter ## Notes for developers +
+Click to expand... + 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 @@ -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 . @@ -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. + +