From ccaf730332ec8fa8d40789c620d5045baf40e804 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicholas=20Kr=C3=A4mer?= Date: Mon, 13 Nov 2023 15:48:38 +0100 Subject: [PATCH 1/3] Add a contribution guide --- .../source/docs_dev/continuous_integration.md | 26 +++++++ docs/source/docs_dev/contribution_guide.md | 76 +++++++++++++------ 2 files changed, 79 insertions(+), 23 deletions(-) create mode 100644 docs/source/docs_dev/continuous_integration.md diff --git a/docs/source/docs_dev/continuous_integration.md b/docs/source/docs_dev/continuous_integration.md new file mode 100644 index 0000000..46443dd --- /dev/null +++ b/docs/source/docs_dev/continuous_integration.md @@ -0,0 +1,26 @@ +# Continuous integration + + +Install `tueplots` with all ci-related dependencies via +``` +pip install .[ci] +``` +Run all checks via +``` +tox +``` +or only run the tests via +``` +tox -e pytest +``` +or use tox (which also runs the linter, and the python-code-snippets in this readme). +``` +tox +``` +The CI checks for compliance of the code with black and isort, and runs the tests and the notebooks. +To automatically satisfy the former, there is a pre-commit that can be used (do this once): +``` +pip install pre-commit +pre-commit install +``` +From then on, your code will be checked for isort and black compatibility automatically. diff --git a/docs/source/docs_dev/contribution_guide.md b/docs/source/docs_dev/contribution_guide.md index ca308ad..e7383be 100644 --- a/docs/source/docs_dev/contribution_guide.md +++ b/docs/source/docs_dev/contribution_guide.md @@ -1,25 +1,55 @@ # Contribution guide -Install `tueplots` with all ci-related dependencies via -``` -pip install .[ci] -``` -Run all checks via -``` -tox -``` -or only run the tests via -``` -tox -e pytest -``` -or use tox (which also runs the linter, and the python-code-snippets in this readme). -``` -tox -``` -The CI checks for compliance of the code with black and isort, and runs the tests and the notebooks. -To automatically satisfy the former, there is a pre-commit that can be used (do this once): -``` -pip install pre-commit -pre-commit install -``` -From then on, your code will be checked for isort and black compatibility automatically. +Contributions from the community drive `tueplots`. +Are you thinking about contributing to `tueplots`? +If yes, that's fantastic! +To make it as easy as possible for you, follow the steps below. + + + +## Is my contribution in scope? + +`tueplots` welcomes all contributions that concern style-files of scientific papers. +Most obviously, new versions of existing style files (e.g., tueplots has `icml2023`, so `icml2025`, `icml2026`, or `icml2027` are in scope), but +new venues are also interesting (e.g., tueplots has ICML's style files, CVPR is also in scope). +For anything else, create an issue, and we will have a look together! + + +## How do I make a pull request on GitHub? +Making a pull request on GitHub can seem complicated if one is not used to doing that, but luckily, there are many guides: + +- [Here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) is GitHub's guide for contributing to open-source projects, including explanations of the terms "cloning" or "forking". +- [Here](https://docs.github.com/en/get-started/using-git) is information about working with `git`. +- And [here](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) is how we can all write better commit messages. +- Using a virtual environment is generally a good idea when working with Python projects (such as `tueplots`). [Here](https://realpython.com/python-virtual-environments-a-primer/) are the basics. Be aware that if you place your environment inside the tueplots root folder, tueplots' auto-formatting might attempt to format the source code inside the environment, which is unnecessary. + +## Where do I put my code? + +Once you've got the basic setup (forks, clones, git) going, it is time to write code. +Check out the [continuous-integration](https://tueplots.readthedocs.io/en/latest/docs_dev/continuous_integration) page for information about installing all dev-related tools. + + +Then, roughly follow these steps: + +1. If you like to add a new style file, it would be ideal if you contributed four things: bundles, figsizes, fontsizes, and fonts. The remaining modules (axes, cycler, markers) are usually unimportant for adding a new style file. +2. Start by adding test cases to `tests/test_rc_params_cases/test_{fontsizes,figsizes,fonts,bundles}.py`. Take the existing cases as a reference. The next time you run `tox`, the tests will fail (which is expected). +3. Fix the failing tests by adding the corresponding functions to `tueplots/{fontsizes, figsizes, fonts, bundles}.py`. A good source for the concrete values of, e.g., the figsizes, are the author instructions that each conference/journal provides. Some values are easy to find; for others, you have to dig deeper. If you cannot find something, contribute what you can! Now, all tests should pass again. +4. A lot of this will be copying/pasting existing code. Remember to update the docstrings of the pasted code. +5. If you like, add a corresponding cell to one of the example notebooks. This step is optional, but sometimes it helps to see the configuration "in action". + + +Commit the results and open a pull request. +In the pull request's description, mention what you have contributed and where one can find the information. For example, write something like this: + + + + Title: Style-file for ICML2026 + + Description: This PR adds the bundles, figsizes, fonts, and fontsizes for ICML 2026. + + Most values are the same as in previous years; see for reference. + + +Once this is done, we will process the pull request as quickly as we can. + +Thank you for contributing to tueplots! From b381d08a34494f6fa142eb56bfb25a557a3d8a54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicholas=20Kr=C3=A4mer?= Date: Mon, 13 Nov 2023 15:51:28 +0100 Subject: [PATCH 2/3] Updated dev guide --- docs/source/docs_dev/contribution_guide.md | 4 ++++ docs/source/index.rst | 1 + 2 files changed, 5 insertions(+) diff --git a/docs/source/docs_dev/contribution_guide.md b/docs/source/docs_dev/contribution_guide.md index e7383be..3a7a7bb 100644 --- a/docs/source/docs_dev/contribution_guide.md +++ b/docs/source/docs_dev/contribution_guide.md @@ -23,6 +23,10 @@ Making a pull request on GitHub can seem complicated if one is not used to doing - And [here](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) is how we can all write better commit messages. - Using a virtual environment is generally a good idea when working with Python projects (such as `tueplots`). [Here](https://realpython.com/python-virtual-environments-a-primer/) are the basics. Be aware that if you place your environment inside the tueplots root folder, tueplots' auto-formatting might attempt to format the source code inside the environment, which is unnecessary. + +A small project like tueplots might be the perfect place to start contributing to open-source projects. +If you would like to help but do not know where to start, reach out! + ## Where do I put my code? Once you've got the basic setup (forks, clones, git) going, it is time to write code. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9ace2f7..efc7ca7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -62,6 +62,7 @@ For further details on the available bundles, check out the `tueplots.bundles AP :caption: Developer documentation docs_dev/contribution_guide + docs_dev/continuous_integration docs_dev/examples From babdd9913252d807429d0e9625b6dc23c805bb46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicholas=20Kr=C3=A4mer?= Date: Mon, 13 Nov 2023 15:54:45 +0100 Subject: [PATCH 3/3] Fixed conflicts with links --- docs/source/docs_dev/contribution_guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/docs_dev/contribution_guide.md b/docs/source/docs_dev/contribution_guide.md index 3a7a7bb..4c7066d 100644 --- a/docs/source/docs_dev/contribution_guide.md +++ b/docs/source/docs_dev/contribution_guide.md @@ -10,21 +10,21 @@ To make it as easy as possible for you, follow the steps below. ## Is my contribution in scope? `tueplots` welcomes all contributions that concern style-files of scientific papers. -Most obviously, new versions of existing style files (e.g., tueplots has `icml2023`, so `icml2025`, `icml2026`, or `icml2027` are in scope), but -new venues are also interesting (e.g., tueplots has ICML's style files, CVPR is also in scope). +Most obviously, new versions of existing style files (e.g., `tueplots` has `icml2023`, so `icml2025`, `icml2026`, or `icml2027` are in scope), but +new venues are also interesting (e.g., `tueplots` has ICML's style files, CVPR is also in scope). For anything else, create an issue, and we will have a look together! ## How do I make a pull request on GitHub? Making a pull request on GitHub can seem complicated if one is not used to doing that, but luckily, there are many guides: -- [Here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) is GitHub's guide for contributing to open-source projects, including explanations of the terms "cloning" or "forking". +- [This](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) is GitHub's guide for contributing to open-source projects, including explanations of the terms "cloning" or "forking". - [Here](https://docs.github.com/en/get-started/using-git) is information about working with `git`. -- And [here](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) is how we can all write better commit messages. -- Using a virtual environment is generally a good idea when working with Python projects (such as `tueplots`). [Here](https://realpython.com/python-virtual-environments-a-primer/) are the basics. Be aware that if you place your environment inside the tueplots root folder, tueplots' auto-formatting might attempt to format the source code inside the environment, which is unnecessary. +- And [this is how](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) we can all write better commit messages. +- Using a virtual environment is generally a good idea when working with Python projects (such as `tueplots`). [This guide](https://realpython.com/python-virtual-environments-a-primer/) describes the basics. Be aware that if you place your environment inside the `tueplots` root folder, `tueplots`' auto-formatting might attempt to format the source code inside the environment, which is unnecessary. -A small project like tueplots might be the perfect place to start contributing to open-source projects. +A small project like `tueplots` might be the perfect place to start contributing to open-source projects. If you would like to help but do not know where to start, reach out! ## Where do I put my code?