third_party/rust/uuid/CONTRIBUTING.md

   1 Contributing to Uuid
   2 ---
   3 [Contributing to Uuid]: #contributing-to-uuid
   4
   5 Thank you for your interest in contributing to the Uuid Project!
   6
   7 * [Feature Requests](#feature-requests)
   8 * [Bug Reports](#bug-reports)
   9 * [Pull Requests](#pull-requests)
  10 * [Writing Documentation](#writing-documentation)
  11 * [Issue Triage](#issue-triage)
  12 * [Out-of-tree Contributions](#out-of-tree-contributions)
  13 * [Helpful Links](#helpful-links)
  14
  15 For any questions, please make a post on [Discussions] or [users.rust-lang.org][u-r-l-o].
  16
  17 > All contributors need to follow our [Code of Conduct].
  18
  19 [Code of Conduct]: CODE_OF_CONDUCT.md
  20
  21 # Feature Requests
  22 [Feature Requests]: #feature-requests
  23
  24 The `uuid` crate is stable so features that require breaking changes can't be
  25 accepted. There are bound to be usability gaps that can be filled with non-breaking
  26 features though!
  27
  28 If you have the chance, please [search existing issues], as there is a chance
  29 that someone has already requested your feature.
  30
  31 File your feature request with a descriptive title, as this helps others find
  32 your request.
  33
  34 You can request your feature by following [this link][Feature Request Link] and
  35 filling it in.
  36
  37 > We welcome pull requests for your own feature requests. Discussion should stay
  38 on the relevant issue to make it easier to find.
  39
  40 ## Adding new unstable dependencies
  41
  42 If a feature introduces a new unstable dependency then it needs to be private.
  43 That means traits and types from the unstable library can't be visible in `uuid`'s
  44 own public API.
  45
  46 To implement unstable traits, see the precedent set by the `zerocopy-unstable` feature.
  47 It implements a public unstable trait on `Uuid`, but uses the `uuid_unstable` cfg flag.
  48
  49 [Feature Request Link]: https://github.com/uuid-rs/uuid/issues/new?template=Feature_request.md
  50
  51 # Bug Reports
  52 [Bug Reports]: #bug-reports
  53
  54 While no one likes bugs, they are an unfortunate reality in software. Remember
  55 we can't fix bugs we don't know about, so don't be shy about reporting.
  56
  57 If you have the chance, please [search existing issues], as there is a chance
  58 that someone has already reported your error. This isn't strictly needed, as
  59 sometimes you might not what exactly you are looking for.
  60
  61 File your issue with a descriptive title, as this helps others find your issue.
  62
  63 Reporting a bug is as easy as following [this link][Bug Report Link] and
  64 filling it in.
  65
  66 Sometimes a backtrace may be needed. In that case, set `RUST_BACKTRACE`
  67 environment variable to `1`. For example:
  68
  69 ```bash
  70 $ RUST_BACKTRACE=1 cargo build
  71 ```
  72
  73 > We welcome pull requests for your own bug reports, provided they have been
  74 discussed.
  75
  76 [Bug Report Link]: https://github.com/uuid-rs/uuid/issues/new?template=Bug_report.md
  77
  78 # Pull Requests
  79 [Pull Requests]: #pull-requests
  80
  81 Pull requests(PRs) are the primary mechanism we use to change Uuid. GitHub itself
  82 has some [great documentation] on using the Pull Request feature. We use the
  83 "fork and pull" model described [here][fnp], where contributors push changes to
  84 their personal fork and create pull requests to bring those changes into the
  85 source repository.
  86
  87 Unless the changes are fairly minor (like documentation changes or tiny
  88 patches), we require PRs to relevant issues.
  89
  90 Please open PRs against the `main` branch.
  91
  92 When you feel that the PR is ready, please ping one of the maintainers so
  93 they can review your changes.
  94
  95 [great documentation]: https://help.github.com/articles/about-pull-requests/
  96 [fnp]: https://help.github.com/articles/about-collaborative-development-models/
  97
  98 # Writing Documentation
  99 [Writing Documentation]: #writing-documentation
 100
 101 Documentation is an important part of Uuid. Lackluster or incorrect
 102 documentation can cause headaches for the users of `uuid`. Therefore,
 103 improvements to documentation are always welcome.
 104
 105 We follow the documentation style guidelines as given by [RFC 1574].
 106
 107 [RFC 1574]: https://github.com/rust-lang/rfcs/blob/main/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 108
 109 # Issue Triage
 110 [Issue Triage]: #issue-triage
 111
 112 Sometimes, an issue might stay open even after the relevant bug has been fixed.
 113 Other times, the bug report may become invalid. Or we may just forget about the
 114 bug.
 115
 116 You can help to go through old bug reports and check if they are still valid.
 117 You can follow [this link][lrus] to look for issues like this.
 118
 119 [lrus]: https://github.com/uuid-rs/uuid/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 120
 121 # Fuzzing
 122 We use [`cargo fuzz`] to fuzz test various parts of `uuid`. See their guide
 123 for more details on what fuzzing is and how to run the tests yourself.
 124
 125 # Helpful Links
 126 [Helpful Links]: #helpful-links
 127
 128 For people new to Uuid, and just starting to contribute, or even for more
 129 seasoned developers, some useful places to look for information are:
 130
 131 * The Wikipedia entry on [Universally Unique Identifier][wiki-uuid].
 132 * [RFC 4122] which gives the specification of Uuids.
 133
 134 [wiki-uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
 135 [RFC 4122]: https://www.ietf.org/rfc/rfc4122.txt
 136
 137 [u-r-l-o]: https://users.rust-lang.org
 138 [Discussions]: https://github.com/uuid-rs/uuid/discussions
 139 [search existing issues]: https://github.com/uuid-rs/uuid/search?q=&type=Issues&utf8=%E2%9C%93
 140 [`cargo fuzz`]: https://rust-fuzz.github.io/book/cargo-fuzz.html