| # Contribute to dartdoc |
| |
| To _use_ the dartdoc tool, see the [user docs][]. |
| This page contains information relevant for contributors to the dartdoc project. |
| |
| ## Can I help? |
| |
| Yes! |
| |
| Start by [using the tool](README.md) and filing issues and requests. |
| |
| See the [dartdoc API](https://pub.dev/documentation/dartdoc/latest/) docs, |
| generated by dartdoc. |
| |
| If you want to contribute, check out the [issue tracker][] and |
| see if there's an issue that you're passionate about. |
| If you want to add a new feature that's not yet in the issue tracker, |
| start by opening an issue. Thanks! |
| |
| [](https://github.com/dart-lang/dartdoc/actions?query=workflow%3ATest) |
| |
| ## Making Changes |
| |
| 1. When a change is user-facing, please add a new entry |
| to the [changelog][] under the current `-wip` version. |
| 2. Please include a test for your change. `dartdoc` has both |
| `package:test`-style unit tests as well as integration tests. |
| To run the tests, use `dart run tool/task.dart test`. |
| 3. For major changes, run both `dart run tool/task.dart compare sdk-warnings` |
| and `dart run tool/task.dart compare flutter-warnings`, and |
| include the summary results in your pull request. |
| 4. Be sure to format your Dart code using `dart format`, |
| otherwise our CI will complain. |
| 5. Use `dart run tool/task.dart buildbot` before creating a pull request |
| to quickly check for common problems. |
| Follow any instructions it outputs, then run again. |
| 6. Post your change via a pull request for review and integration! |
| |
| ## Testing |
| |
| dartdoc has a number of utility command that can be used to |
| check for behavior changes or try out your change on arbitrary packages. |
| |
| ```bash |
| # Serve the latest version of the given package locally on port 9000. |
| dart run tool/task.dart serve package --name=intl |
| |
| # Build the SDK docs with the head version and compare its warning |
| # output and (rough) performance to the main version. |
| dart run tool/task.dart compare sdk-warnings |
| |
| # Serve the flutter docs built with the head version on port 8001. |
| dart run tool/task.dart serve flutter |
| |
| # Serve the test package (testing/test_package) on port 8002 |
| dart run tool/task.dart serve testing-package |
| ``` |
| |
| There are more commands added all the time, |
| check out `tool/task.dart` to find each command or |
| learn how they are implemented. |
| |
| ## License |
| |
| Please see the [dartdoc license][]. |
| |
| [user docs]: https://github.com/dart-lang/dartdoc#dart-documentation-generator |
| [issue tracker]: https://github.com/dart-lang/dartdoc/issues |
| [changelog]: https://github.com/dart-lang/dartdoc/blob/main/CHANGELOG.md |
| [dartdoc license]: https://github.com/dart-lang/dartdoc/blob/main/LICENSE |
