diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..07d4056b --- /dev/null +++ b/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. + + + + +[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 + diff --git a/README.md b/README.md index 49c8c05c..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,36 +97,24 @@ pip install cookiecutter ## Notes for developers -### Contributing +
+Click to expand... -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. +