Skip to content

Commit

Permalink
Add a "Where do i find styles" section to the contribution guide (#127)
Browse files Browse the repository at this point in the history
* Add information about source-code fonts

* Fixed a few formulations

* Updated a link
  • Loading branch information
pnkraemer authored Nov 20, 2023
1 parent 8b10cfd commit 0d73577
Showing 1 changed file with 31 additions and 7 deletions.
38 changes: 31 additions & 7 deletions docs/source/docs_dev/contribution_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
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.
To make it as easy as possible, follow the steps below.



Expand All @@ -14,18 +14,42 @@ Most obviously, new versions of existing style files (e.g., `tueplots` has `icml
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!

## Where do I find the style files?

A good source for the concrete values of, e.g., the figure sizes, are the conference's/journal's instructions for the authors.
Some values are easy to find; for others, you have to dig deeper.
The figure size and font size are usually mentioned fairly prominently.
When implementing the font size in Tueplots, use the Figure captions as a reference, not the main text.

The correct font implementation can sometimes be tricky because most templates use 'Times'; however, there are different ways of achieving a "Times"-like font.
One often has to look at the source code for the Latex style file to find the correct font.
Look out for the following information:

* If the document uses `\includepackage{times}`, then the template uses the 'Times' font. Use the same font configuration as ICLR-2023.
* If the document uses `\includepackage{ptm}`, the template also uses the 'Times' font but with a different package. Tueplots attempts to mirror this choice as closely as possible (by including the same package as the Latex template) even if it means including an obsolete package ([the 'times' package is obsolete](https://ctan.org/pkg/times)) .
* If the document includes no font-related package, it likely uses Computer Modern. Copy the configuration from JMLR-2001.

**Note 1:**
The `times` vs `ptm` usage in Tueplots has been clarified by [pull request #125](https://github.com/pnkraemer/tueplots/pull/125) and does not affect version `v0.0.12` or older.

**Note 2:**
[Times and Times New Roman are different fonts](https://creativepro.com/times-roman-vs-times-new-roman/).
And since there is no native Times New Roman implementation in Latex unless one uses XeLatex ([see this link](https://tex.stackexchange.com/questions/153168/how-to-set-document-font-to-times-new-roman-by-command)), be sceptical if a template claims to use Times New Roman but provides a Latex style file.
Always consult the style file's source code to identify the correct font.



## 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:

- [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 [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 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.
If you would like to help but do not know where to start, reach out!
If you want to contribute but need help knowing where to start, reach out!

## Where do I put my code?

Expand All @@ -36,14 +60,14 @@ Check out the [continuous-integration](https://tueplots.readthedocs.io/en/latest
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.
2. Add 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`. 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:
In the pull request's description, mention what it contributes and where to find the information. For example, write something like this:



Expand All @@ -54,6 +78,6 @@ In the pull request's description, mention what you have contributed and where o
Most values are the same as in previous years; see <link-to-call-for-papers> for reference.


Once this is done, we will process the pull request as quickly as we can.
Once this is done, we will try to process the pull request as quickly as possible.

Thank you for contributing to tueplots!

0 comments on commit 0d73577

Please sign in to comment.