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