Added CONTRIBUTING.md and modified README.md

CONTRIBUTING.md

@@ -0,0 +1,141 @@
+# Contributing to pybamm-cookiecutter
+
+If you'd like to contribute to this project, please have a look at the [guidelines below](#workflow).
+
+If you're already familiar with our workflow, maybe have a quick look at the [pre-commit checks](#pre-commit-checks) directly below.
+
+## Pre-commit checks
+
+Before you commit any code, please perform the following checks:
+
+- [All tests pass](#testing): `$ nox -s test-generation`
+- [The documentation builds](#building-the-documentation): `$ nox -s docs`
+
+### Installing and using pre-commit
+
+`pybamm-cookiecutter` uses a set of `pre-commit` hooks and the `pre-commit` bot to format and prettify the codebase. The hooks can be installed locally using -
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using -
+
+```bash
+pre-commit run --all-files
+```
+
+If you would like to skip the failing checks and push the code for further discussion, use the `--no-verify` option with `git commit`.
+
+## Workflow
+
+We use [GIT](https://en.wikipedia.org/wiki/Git) and [GitHub](https://en.wikipedia.org/wiki/GitHub) to coordinate our work. When making any kind of update, we try to follow the procedure below.
+
+### A. Before you begin
+
+1. Create an [issue](https://guides.github.com/features/issues/) where new proposals can be discussed before any coding is done.
+2. Create a [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) of this repo (ideally on your own [fork](https://help.github.com/articles/fork-a-repo/)), where all changes will be made.
+3. Download the source code onto your local system, by [cloning](https://help.github.com/articles/cloning-a-repository/) the repository (or your fork of the repository).
+4. Use `nox -s dev` or `pip install -e .[dev]` to install pybamm-cookiecutter with the developer options.
+5. [Test](#testing) if your installation worked, using the test script: `nox -s test-generation` or `pytest tests/`.
+
+You now have everything you need to start making changes!
+
+### B. Writing your code
+
+6. This project is developed in [Python](https://www.python.org)), and uses [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) templating tool. For testing we use [Pytest](https://docs.pytest.org/en/).
+7. Make sure to follow our [coding style guidelines](#coding-style-guidelines).
+8. Commit your changes to your branch with [useful, descriptive commit messages](https://chris.beams.io/posts/git-commit/): Remember these are
+   publicly visible and should still make sense a few months ahead in time.
+   While developing, you can keep using the GitHub issue you're working on
+   as a place for discussion.
+
+### C. Merging your changes with pybamm-cookiecutter
+
+9. [Test your code!](#testing)
+10. When you feel your code is finished, or at least warrants serious discussion, run the [pre-commit checks](#pre-commit-checks) and then create a [pull request](https://help.github.com/articles/about-pull-requests/) (PR) on [pybamm-cookiecutter's GitHub page](https://github.com/pybamm-team/pybamm-cookiecutter).
+11. Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into pybamm-cookiecutter main repository.
+
+
+## Coding style guidelines
+
+This project follows the [PEP8 recommendations](https://www.python.org/dev/peps/pep-0008/) for coding style. These are very common guidelines, and community tools have been developed to check how well projects implement them. We recommend using pre-commit hooks to check your code before committing it. See [installing and using pre-commit](#installing-and-using-pre-commit) section for more details.
+
+### Ruff
+
+We use [ruff](https://github.com/charliermarsh/ruff) to check our PEP8 adherence. To try this on your system, navigate to the parent pybamm-cookiecutter directory in a console and type
+
+```bash
+python -m pip install pre-commit
+pre-commit run ruff
+```
+
+ruff is configured inside the file `pre-commit-config.yaml`, allowing us to ignore some errors. If you think this should be added or removed, please submit an [issue](https://github.com/pybamm-team/pybamm-cookiecutter/issues).
+
+When you commit your changes they will be checked against ruff automatically (see [Pre-commit checks](#pre-commit-checks)).
+
+### Naming
+
+Naming is hard. In general, we aim for descriptive class, method, and argument names. Avoid abbreviations when possible without making names overly long, so `mean` is better than `mu`, but a class name like `MyClass` is fine.
+
+Class names are CamelCase, and start with an upper case letter, for example `MyOtherClass`. Method and variable names are lower case, and use underscores for word separation, for example `x` or `iteration_count`.
+
+## Testing
+
+All code requires testing. We use the [Pytest](https://docs.pytest.org/en/) package for our tests. (These tests typically just check that the code runs without error, and so, are more _debugging_ than _testing_ in a strict sense. Nevertheless, they are very useful to have!).
+
+If you have `nox` installed, to run tests, type
+
+```bash
+nox -s test-generation
+```
+
+else, type
+
+```bash
+pytest tests/
+```
+
+### Writing tests
+
+Every new feature should have its own test. To create ones, have a look at the `test` directory and see if there's a test for a similar method. Copy-pasting this is a good way to start.
+
+Next, add some simple (and speedy!) tests of your main features. If these run without exceptions that's a good start! Next, check the output of your methods using any of these [assert methods](https://docs.python.org/3.3/library/unittest.html#assert-methods).
+
+
+## Documentation
+
+First and foremost, every method and every class should have a [docstring](https://www.python.org/dev/peps/pep-0257/) that describes in plain terms what it does, and what the expected input and output is.
+
+These docstrings can be fairly simple, but can also make use of [reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html), a markup language designed specifically for writing [technical documentation](https://en.wikipedia.org/wiki/ReStructuredText).
+
+Using [Sphinx](http://www.sphinx-doc.org/en/stable/) the documentation in `docs` can be converted to HTML, PDF, and other formats. In particular, we use it to generate the documentation on http://docs.pybamm.org/
+
+### Building the documentation
+
+To test and debug the documentation, it's best to build it locally. To do this, navigate to your pybamm-cookiecutter directory in a console, and then type (on GNU/Linux, macOS, and Windows):
+
+```
+nox -s docs
+```
+
+And then visit the webpage served at `http://127.0.0.1:8000`. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded. In CI, the docs are built and tested using the `docs` session in the `noxfile.py` file with warnings turned into errors, to fail the build. The warnings can be removed or ignored by adding the appropriate warning identifier to the `suppress_warnings` list in `docs/conf.py`.
+
+### Continuous Integration using GitHub Actions
+
+Each change pushed to the pybamm-cookiecutter GitHub repository will trigger the tests to be run, using [GitHub Actions](https://github.com/features/actions).
+
+Tests are run for different operating systems, and for all Python versions officially supported by pybamm-cookiecutter template. If you opened a Pull Request, feedback is directly available on the corresponding page. If all tests pass, a green tick will be displayed next to the corresponding test run. If one or more test(s) fail, a red cross will be displayed instead.
+
+More details can be obtained by clicking on a specific run.
+
+Configuration files for various GitHub actions workflow can be found in `.github/workflows`.
+
+### GitHub
+
+GitHub does some magic with particular filenames. In particular:
+
+- The first page people see when they go to [our GitHub page](https://github.com/pybamm-team/pybamm-cookiecutter) displays the contents of [README.md](https://github.com/pybamm-team/pybamm-cookiecutter/blob/main/README.md), which is written in the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Some guidelines can be found [here](https://help.github.com/articles/about-readmes/).
+- The license for using pybamm-cookiecutter is stored in [LICENSE](https://github.com/pybamm-team/pybamm-cookiecutter/blob/main/LICENSE.txt), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
+- This file, [CONTRIBUTING.md](https://github.com/pybamm-team/pybamm-cookiecutter/blob/main/CONTRIBUTING.md) is recognised as the contribution guidelines and a link is [automatically](https://github.com/blog/1184-contributing-guidelines) displayed when new issues or pull requests are created.

README.md

@@ -22,5 +22,59 @@
 [pypi-version]:             https://img.shields.io/pypi/v/pybamm-cookiecutter
 [rtd-badge]:                https://readthedocs.org/projects/pybamm-cookiecutter/badge/?version=latest
 [rtd-link]:                 https://pybamm-cookiecutter.readthedocs.io/en/latest/?badge=latest -->
+[![Powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](http://numfocus.org)
 
 This repository contains a `cookiecutter` template for battery modeling projects using PyBaMM, released under the [BSD-3-Clause license](LICENSE). Currently under active development.
+
+## 📄 Using pybamm-cookiecutter
+
+### Generating projects with pybamm-cookiecutter
+
+This template is not on PyPi so it cannot be installed through pip until the first release. Meanwhile it can be used by cloning this repository and using cookiecutter to generate a project with this template.
+
+To use pybamm-cookiecutter template, first clone this repository on your local machine.
+```bash
+git clone https://github.com/pybamm-team/pybamm-cookiecutter.git
+```
+Create a temporary virtual environment inside the reposiory and activate it.
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+Install cookiecutter and generate the project using the pybamm-cookiecutter template by moving outside the parent pybamm-cookiecutter directory.
+```bash
+pip install cookiecutter
+cookiecutter pybamm-cookiecutter/
+```
+Cookiecutter will prompt you with various configurations and you may choose the ones that suit your use case.
+
+
+### Installing the pybamm_cookiecutter project
+
+This is our version of the project generated using the cookiecutter template. There are two ways to install this project, either through nox or pip.
+To install navigate to the root directory of this repository and execute either of these commands.
+
+`nox -s dev`
+or
+`pip install -e .[dev]`
+
+To check if the project was successfully installed import the project inside python.
+
+```python
+import pybamm_cookiecutter
+
+pybamm_cookiecutter._version.version
+```
+
+## 🛠️ Contributing to PyBaMM
+
+If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these [guidelines](https://github.com/pybamm-team/pybamm-cookiecutter/blob/main/CONTRIBUTING.md) first.
+
+## 📫 Get in touch
+
+For any questions, comments, suggestions or bug reports, please see the
+[contact page](https://www.pybamm.org/community).
+
+## 📃 License
+
+pybamm-cookiecutter is fully open source. For more information about its license, see [LICENSE](https://github.com/pybamm-team/pybamm-cookiecutter/blob/main/LICENSE.txt).