1  # Contributing
  2  
  3  Contributions are welcome, and they are greatly appreciated!
  4  Every little bit helps, and credit will always be given.
  5  
  6  ## Environment setup
  7  
  8  Nothing easier!
  9  
 10  Fork and clone the repository, then:
 11  
 12  ```bash
 13  cd docstrings2pep727
 14  make setup
 15  ```
 16  
 17  > NOTE:
 18  > If it fails for some reason,
 19  > you'll need to install
 20  > [PDM](https://github.com/pdm-project/pdm)
 21  > manually.
 22  >
 23  > You can install it with:
 24  >
 25  > ```bash
 26  > python3 -m pip install --user pipx
 27  > pipx install pdm
 28  > ```
 29  >
 30  > Now you can try running `make setup` again,
 31  > or simply `pdm install`.
 32  
 33  You now have the dependencies installed.
 34  
 35  You can run the application with `pdm run docstrings2pep727 [ARGS...]`.
 36  
 37  Run `make help` to see all the available actions!
 38  
 39  ## Tasks
 40  
 41  This project uses [duty](https://github.com/pawamoy/duty) to run tasks.
 42  A Makefile is also provided. The Makefile will try to run certain tasks
 43  on multiple Python versions. If for some reason you don't want to run the task
 44  on multiple Python versions, you run the task directly with `pdm run duty TASK`.
 45  
 46  The Makefile detects if a virtual environment is activated,
 47  so `make` will work the same with the virtualenv activated or not.
 48  
 49  If you work in VSCode, we provide
 50  [an action to configure VSCode](https://pawamoy.github.io/copier-pdm/work/#vscode-setup)
 51  for the project.
 52  
 53  ## Development
 54  
 55  As usual:
 56  
 57  1. create a new branch: `git switch -c feature-or-bugfix-name`
 58  1. edit the code and/or the documentation
 59  
 60  **Before committing:**
 61  
 62  1. run `make format` to auto-format the code
 63  1. run `make check` to check everything (fix any warning)
 64  1. run `make test` to run the tests (fix any issue)
 65  1. if you updated the documentation or the project dependencies:
 66      1. run `make docs`
 67      1. go to http://localhost:8000 and check that everything looks good
 68  1. follow our [commit message convention](#commit-message-convention)
 69  
 70  If you are unsure about how to fix or ignore a warning,
 71  just let the continuous integration fail,
 72  and we will help you during review.
 73  
 74  Don't bother updating the changelog, we will take care of this.
 75  
 76  ## Commit message convention
 77  
 78  Commit messages must follow our convention based on the
 79  [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message)
 80  or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
 81  
 82  ```
 83  <type>[(scope)]: Subject
 84  
 85  [Body]
 86  ```
 87  
 88  **Subject and body must be valid Markdown.**
 89  Subject must have proper casing (uppercase for first letter
 90  if it makes sense), but no dot at the end, and no punctuation
 91  in general.
 92  
 93  Scope and body are optional. Type can be:
 94  
 95  - `build`: About packaging, building wheels, etc.
 96  - `chore`: About packaging or repo/files management.
 97  - `ci`: About Continuous Integration.
 98  - `deps`: Dependencies update.
 99  - `docs`: About documentation.
100  - `feat`: New feature.
101  - `fix`: Bug fix.
102  - `perf`: About performance.
103  - `refactor`: Changes that are not features or bug fixes.
104  - `style`: A change in code style/format.
105  - `tests`: About tests.
106  
107  If you write a body, please add trailers at the end
108  (for example issues and PR references, or co-authors),
109  without relying on GitHub's flavored Markdown:
110  
111  ```
112  Body.
113  
114  Issue #10: https://github.com/namespace/project/issues/10
115  Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15
116  ```
117  
118  These "trailers" must appear at the end of the body,
119  without any blank lines between them. The trailer title
120  can contain any character except colons `:`.
121  We expect a full URI for each trailer, not just GitHub autolinks
122  (for example, full GitHub URLs for commits and issues,
123  not the hash or the #issue-number).
124  
125  We do not enforce a line length on commit messages summary and body,
126  but please avoid very long summaries, and very long lines in the body,
127  unless they are part of code blocks that must not be wrapped.
128  
129  ## Pull requests guidelines
130  
131  Link to any related issue in the Pull Request message.
132  
133  During the review, we recommend using fixups:
134  
135  ```bash
136  # SHA is the SHA of the commit you want to fix
137  git commit --fixup=SHA
138  ```
139  
140  Once all the changes are approved, you can squash your commits:
141  
142  ```bash
143  git rebase -i --autosquash main
144  ```
145  
146  And force-push:
147  
148  ```bash
149  git push -f
150  ```
151  
152  If this seems all too complicated, you can push or force-push each new commit,
153  and we will squash them ourselves if needed, before merging.