# Contributing

Welcome to the GitLab bindings crate for Rust! This crate aims to offer
definitions of all of GitLab's API endpoints. The API patterns involved are
documented in [this blog post][designing-rust-bindings-for-rest-apis].

[designing-rust-bindings-for-rest-apis]: https://plume.benboeckel.net/~/JustAnotherBlog/designing-rust-bindings-for-rest-ap-is

This design means that this crate aims to define:

- basic endpoint types
- endpoint combinators
- authentication mechanisms
- endpoint definitions themselves

It also means that it does *not* provide:

- definitions for response types
- server-version-aware variants of the API

Eventually, the API should adhere to semver, but it is hard to give a timeline.

## Type definitions and webhooks

Older releases of this crate tried to define endpoints as methods and define
the response types. This did not scale well. As such, the `types` module is
deprecated as of `0.1609.0`.

The `hooks`, `systemhooks`, and `webhooks` are hard to provide semver
guarantees and may be migrated to their own crate in the future.

None of the hook or types modules provide any semver guarantees.

## Guidelines

### Implementing an endpoint

- [ ] Add an entry to `CHANGELOG.md`. If there is no new section after a
      release, add a new section with a bumped patch number and ` (unreleased)`
      after the new version number.
- [ ] Update `src/api/README.md`:
  - [ ] Move the endpoint from the `Todo` section to the `Implemented` section,
        keeping things sorted.
  - [ ] If implementing an API from a page in the `Endpoint groups` section,
        please add all unimplemented endpoints to the `Todo` list and remove
        the entry from the list of files.
- [ ] All `Endpoint` structs must be `Clone`.
- [ ] Use `#[builder(setter(strip_option))]` if-and-only-if the endpoint has
      `Option` parameters.
- [ ] For `BTreeSet` and/or `Vec` parameters, make the default builder methods
      private and offer:
      - [ ] a method to reset and/or remove items
      - [ ] a method to add a single item
      - [ ] a method to add a sequence of items from an `Iterator` (if
            sensible)
- [ ] Test that each required parameter is actually required by providing all
      required parameters except the parameter under test.
- [ ] For each optional parameter, add a test which provides the required
      parameters and the single optional parameter.
- [ ] Expose the endpoint, its builder, and its builder error in the parent
      module.
- [ ] Consider whether the endpoint should `impl Pageable` or not.

### Adding a new parameter

- [ ] Add an entry to `CHANGELOG.md`. If there is no new section after a
      release, add a new section with a bumped patch number and ` (unreleased)`
      after the new version number.
- [ ] All `enum` types backing parameters should (generally) be
      `#[non_exhaustive]` because GitLab can add new variants at any time.
- [ ] Add tests for all `enum` types implementing `ParamQuery` and `Default`.
- [ ] Expose any new `enum` types in the parent module.