No puede seleccionar más de 25 temas Los temas deben comenzar con una letra o número, pueden incluir guiones ('-') y pueden tener hasta 35 caracteres de largo.

CONTRIBUTING.md 5.1 KiB

hace 4 años
hace 4 años
hace 4 años
hace 4 años
hace 4 años
hace 4 años
hace 4 años
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
  1. # Contributing to Kosmorro
  2. If you are reading this, then you are probably looking for a way to contribute to Kosmorro (you're in the good place!). Thank you!
  3. There are multiple ways to contribute that can match with your possibilities.
  4. ## Opening issues
  5. ### Reporting bugs
  6. If you found a bug, please check it is not already reported in the _Issues_ tab.
  7. If it is not, [create a bug report](https://github.com/Deuchnord/kosmorro/issues/new/choose) and fill in the template that offers to you. Feel free to give as much information as possible, as it will make the bug easier to fix.
  8. ### Suggest a new feature
  9. Have an idea of feature you think would be nice on Kosmorro? Time to suggest it!
  10. First, please check someone didn't suggest your next revolution in the _Issues_ tab. If it's not, [create a feature request](https://github.com/Deuchnord/kosmorro/issues/new/choose) and fill in the templace that offers to you.
  11. ## Translating
  12. If you speak another language than English, another nice way to enhance Kosmorro is to translate its messages. The recommended way to begin translating Kosmorro is to [join the Weblate project](https://hosted.weblate.org/engage/kosmorro/).
  13. ## Writing code
  14. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Kosmorro/kosmorro)
  15. First, if you are fixing an opened issue, check that nobody is already working on it — if someone seems to be but their Pull Request seems stuck, please ask them first if you can continue the development. If you retake the code they produced, **don't change the author of the commits**.
  16. Before writing the code, first create a fork of the repository and clone it. You may also want to add the original repository (`Kosmorro/kosmorro`), so you can update your fork with the last upstream commits.
  17. Then create a new branch and start coding. Finally, commit and push, then open a PR on this project. If your project is not complete, feel free to open it as Draft, then mark it as ready for review when you're done.
  18. ### Choosing the right target branch
  19. Whatever you are doing, always base your working branch on `master`.
  20. When you create your PR, please consider selecting the right target branch:
  21. - If you are fixing a bug or optimizing something, then target the `master` branch.
  22. - If you are doing anything else, then target the `features` branch.
  23. This allows to make easier to publish patch releases, which have a higher priority than the minor releases.
  24. ### Dealing with the translations
  25. The messages file contains all the messages Kosmorro can display, in order to make them translatable. When you change code, you may change also the messages displayed by the software.
  26. When you add a new string that will be displayed to the end user, please pass it to the `_()` function made available in the `kosmorrolib.i18n` package, for instance:
  27. ```python
  28. # Don't:
  29. print('Note: All the hours are given in UTC.')
  30. # Do:
  31. from kosmorro.i18n import _
  32. print(_('Note: All the hours are given in UTC.'))
  33. ```
  34. This will allow Python's internationalization tool to translate the string in any available language.
  35. Once you have done your work, please remember to tell [Babel](http://babel.pocoo.org) to extract the new strings:
  36. ```bash
  37. make messages
  38. ```
  39. Note that if you forget to update the messages file, the CI will fail.
  40. ### Matching the coding standards
  41. Kosmorro's source code follows the major coding standards of Python (PEPs).
  42. Before marking your Pull Request as ready for review, don't forget to check that the code respects the coding standards with Black:
  43. ```bash
  44. make black
  45. ```
  46. ### Testing the code
  47. The tests are located in the `/tests` folder.
  48. Their principle is pretty simple:
  49. 1. First, we run a Kosmorro command as we would in command line application. We use the [Aurornis](https://pypi.org/project/aurornis/) package to do this.
  50. 2. Then, we test the return of the command against what we expected. We use [PyTest](https://pypi.org/project/pytest/) to do this.
  51. To run the tests, invoke the following command:
  52. ```bash
  53. make tests
  54. # Or, if you have TeXLive installed on your machine (Linux only):
  55. make TEXLIVE_INSTALLED=1 tests
  56. ```
  57. ### Commiting
  58. The commit messages of this project follow the [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/): basically, when you commit your changes, please prefix them with the following:
  59. - **`fix: `** if your changes fix a bug;
  60. - **`feat: `** if your changes add a new feature.
  61. The message of your commit must start with a lowercase.
  62. Finally, if your change introduce a BC-break, add a footer beginning with `BREAKING CHANGE:` and explaining precisely the BC-break.
  63. Once your PR is ready to review, please squash your commits so it contains only one commit.
  64. > To ensure your commits follow this convention, you can use [glint](https://github.com/brigand/glint).
  65. The commit messages are then used to generate the changelog using [`conventional-changelog`](https://github.com/conventional-changelog/conventional-changelog).
  66. ## Licensing and Copyright Attribution
  67. When you open a Pull Request to the project, you agree to license your code under the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).