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