Skip to content

Latest commit

 

History

History
72 lines (56 loc) · 3 KB

CONTRIBUTING.md

File metadata and controls

72 lines (56 loc) · 3 KB
Raw

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.

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.