From 200acc958ca3595556898bc404473a0f579d2ccd Mon Sep 17 00:00:00 2001 From: Emily Rockman Date: Tue, 5 Dec 2023 21:11:42 -0600 Subject: [PATCH 1/4] add contributing doc and dependabot alerts, modify readme --- .../ISSUE_TEMPLATE/implementation-ticket.yml | 58 +++++++++ .github/ISSUE_TEMPLATE/regression-report.yml | 61 +++++++++ .github/dependabot.yml | 15 +++ CONTRIBUTING.md | 117 ++++++++++++++++++ README.md | 64 ++-------- 5 files changed, 261 insertions(+), 54 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/implementation-ticket.yml create mode 100644 .github/ISSUE_TEMPLATE/regression-report.yml create mode 100644 .github/dependabot.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/implementation-ticket.yml b/.github/ISSUE_TEMPLATE/implementation-ticket.yml new file mode 100644 index 00000000..2636d646 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/implementation-ticket.yml @@ -0,0 +1,58 @@ +name: 🛠️ Implementation +description: This is an implementation ticket intended for use by the maintainers of dbt-oss-template +title: "[] " +labels: ["user docs"] +body: + - type: markdown + attributes: + value: This is an implementation ticket intended for use by the maintainers of dbt-oss-template + - type: checkboxes + attributes: + label: Housekeeping + description: > + A couple friendly reminders: + 1. Remove the `user docs` label if the scope of this work does not require changes to https://docs.getdbt.com/docs: no end-user interface (e.g. yml spec, CLI, error messages, etc) or functional changes + 2. Link any blocking issues in the "Blocked on" field under the "Core devs & maintainers" project. + options: + - label: I am a maintainer of dbt-oss-template + required: true + - type: textarea + attributes: + label: Short description + description: | + Describe the scope of the ticket, a high-level implementation approach and any tradeoffs to consider + validations: + required: true + - type: textarea + attributes: + label: Acceptance criteria + description: | + What is the definition of done for this ticket? Include any relevant edge cases and/or test cases + validations: + required: true + - type: textarea + attributes: + label: Impact to Other Teams + description: | + Will this change impact other teams? Include details of the kinds of changes required (new tests, code changes, related tickets) and _add the relevant `Impact:[team]` label_. + placeholder: | + Example: This change impacts `dbt-redshift` because the tests will need to be modified. The `Impact:[Adapter]` label has been added. + validations: + required: true + - type: textarea + attributes: + label: Will backports be required? + description: | + Will this change need to be backported to previous versions? Add details, possible blockers to backporting and _add the relevant backport labels `backport 1.x.latest`_ + placeholder: | + Example: Backport to 1.6.latest, 1.5.latest and 1.4.latest. Since 1.4 isn't using click, the backport may be complicated. The `backport 1.6.latest`, `backport 1.5.latest` and `backport 1.4.latest` labels have been added. + validations: + required: true + - type: textarea + attributes: + label: Context + description: | + Provide the "why", motivation, and alternative approaches considered -- linking to previous refinement issues, spikes, Notion docs as appropriate + validations: + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/regression-report.yml b/.github/ISSUE_TEMPLATE/regression-report.yml new file mode 100644 index 00000000..766e4efb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/regression-report.yml @@ -0,0 +1,61 @@ +name: ☣️ Regression +description: Report a regression you've observed in a newer version of dbt-oss-template +title: "[Regression] <title>" +labels: ["bug", "regression", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this regression report! + - type: checkboxes + attributes: + label: Is this a regression in a recent version of dbt-oss-template? + description: > + A regression is when documented functionality works as expected in an older version of dbt-oss-template, + and no longer works after upgrading to a newer version of dbt-oss-template + options: + - label: I believe this is a regression in dbt-oss-template functionality + required: true + - label: I have searched the existing issues, and I could not find an existing issue for this regression + required: true + - type: textarea + attributes: + label: Current Behavior + description: A concise description of what you're experiencing. + validations: + required: true + - type: textarea + attributes: + label: Expected/Previous Behavior + description: A concise description of what you expected to happen. + validations: + required: true + - type: textarea + attributes: + label: Steps To Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. In this environment... + 2. With this config... + 3. Run '...' + 4. See error... + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant log output + description: | + If applicable, log output to help explain your problem. + render: shell + validations: + required: false + - type: textarea + attributes: + label: Additional Context + description: | + Links? References? Anything that will give us more context about the issue you are encountering! + + Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. + validations: + required: false diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..39bbe1a3 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,15 @@ +version: 2 +updates: + # npm dependencies + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + rebase-strategy: "disabled" + + # github dependencies + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + rebase-strategy: "disabled" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4335705e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +** replace `dbt-docs` with your repository name in all docs + + +# Contributing to `dbt-docs` + +`dbt-docs` is a template for open source software projects at dbt Labs. + + +1. [About this document](#about-this-document) +2. [Getting the code](#getting-the-code) +3. [Setting up an environment](#setting-up-an-environment) +4. [Running in development](#running-dbt-docs-in-development) +5. [Testing](#testing) +6. [Debugging](#debugging) +7. [Adding or modifying a changelog entry](#adding-or-modifying-a-changelog-entry) +8. [Submitting a Pull Request](#submitting-a-pull-request) + +## About this document + +There are many ways to contribute to the ongoing development of `dbt-docs`, such as by participating in discussions and issues. We encourage you to first read our higher-level document: ["Expectations for Open Source Contributors"](https://docs.getdbt.com/docs/contributing/oss-expectations). + +The rest of this document serves as a more granular guide for contributing code changes to `dbt-docs` (this repository). It is not intended as a guide for using `dbt-docs`, and some pieces assume a level of familiarity with Javascript development. Specific code snippets in this guide assume you are using macOS or Linux and are comfortable with the command line. + +### Notes + +- **CLA:** Please note that anyone contributing code to `dbt-docs` must sign the [Contributor License Agreement](https://docs.getdbt.com/docs/contributor-license-agreements). If you are unable to sign the CLA, the `dbt-docs` maintainers will unfortunately be unable to merge any of your Pull Requests. We welcome you to participate in discussions, open issues, and comment on existing ones. +- **Branches:** All pull requests from community contributors should target the `main` branch (default). +- **Releases**: This repository is never released in itself. An html file is generated that lives in the dbt-core repository and is released as part of that code base. + +## Getting the code + +### Installing git + +You will need `git` in order to download and modify the source code. + +### External contributors + +If you are not a member of the `dbt-labs` GitHub organization, you can contribute to `dbt-docs` by forking the `dbt-docs` repository. For a detailed overview on forking, check out the [GitHub docs on forking](https://help.github.com/en/articles/fork-a-repo). In short, you will need to: + +1. Fork the `dbt-docs` repository +2. Clone your fork locally +3. Check out a new branch for your proposed changes +4. Push changes to your fork +5. Open a pull request against `dbt-labs/dbt-docs` from your forked repository + +### dbt Labs contributors + +If you are a member of the `dbt-labs` GitHub organization, you will have push access to the `dbt-docs` repo. Rather than forking `dbt-docs` to make your changes, just clone the repository, check out a new branch, and push directly to that branch. + +## Setting up an environment + +## Running `dbt-docs` in development + +### Installation + +After cloning this repository, run: + +```bash +git submodule update --init --recursive +``` + +You'll also need to install bundler if you don't already have it: +```bash +gem install bundler +bundle install +``` + +### Building `dbt-docs` + +To build the css files required for webpack: + +```bash +cd styles +bundle exec jekyll build +cd - +``` + +To build an index.html file: + +```bash +npm install +npx webpack +``` + +### Running `dbt-docs` + +To run the dev server, first copy your `manifest.json` and `catalog.json` files to +the `src/` directory. Then run: + +```bash +npm install +npm start +``` + +## Adding or modifying a CHANGELOG Entry + +We use [changie](https://changie.dev) to generate `CHANGELOG` entries. The changie file you generate in `dbt-docs` will make its way over to the `dbt-core` repository when we migrate your change over there. It will show up in the release notes for `dbt-core`! **Note:** Do not edit the `CHANGELOG.md` directly. Your modifications will be lost. + +Follow the steps to [install `changie`](https://changie.dev/guide/installation/) for your system. + +Once changie is installed and your PR is created for a new feature, simply run the following command and changie will walk you through the process of creating a changelog entry: + +```shell +changie new +``` + +Commit the file that's created and your changelog entry is complete! + +## Submitting a Pull Request + +Code can be merged into the current development branch `main` by opening a pull request. A `dbt-docs` maintainer will review your PR. They may suggest code revision for style or clarity, or request that you add unit or integration test(s). These are good things! We believe that, with a little bit of help, anyone can contribute high-quality code. + +Automated tests run via GitHub Actions. If you're a first-time contributor, all tests (including code checks and unit tests) will require a maintainer to approve. Changes in the `dbt-docs` repository trigger integration tests against Postgres. dbt Labs also provides CI environments in which to test changes to other adapters, triggered by PRs in those adapters' repositories, as well as periodic maintenance checks of each adapter in concert with the latest `dbt-docs` code changes. + +Once all tests are passing and your PR has been approved, a `dbt-docs` maintainer will merge your changes into the active development branch. And that's it! Happy developing :tada: + +Sometimes, the content license agreement auto-check bot doesn't find a user's entry in its roster. If you need to force a rerun, add `@cla-bot check` in a comment on the pull request. diff --git a/README.md b/README.md index 43b3259c..ee35c858 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# dbt docs +# Understanding dbt-docs [dbt](https://github.com/dbt-labs/dbt-core) helps analysts write reliable, modular code using a workflow that closely mirrors software development. @@ -7,62 +7,18 @@ This repository contains code for generating a documentation site for dbt projec --- ### Getting Started -- [What is dbt]? -- Read the [dbt viewpoint] -- [Installation] -- Join the [chat][slack-url] on Slack for live questions and support. +In your dbt project, run `dbt docs generate` then `dbt docs serve`. Learn more about docs [here](https://docs.getdbt.com/reference/commands/cmd-docs). +## Join the dbt Community -## Code of Conduct - -Everyone interacting in the dbt project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. - -[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[slack-url]: https://www.getdbt.com/community/ -[Installation]: https://docs.getdbt.com/docs/installation -[What is dbt]: https://docs.getdbt.com/docs/overview -[dbt viewpoint]: https://docs.getdbt.com/docs/viewpoint - -### Showing dbt docs - -In your dbt project, run `dbt docs generate` then `dbt docs serve`. - -### Development - -After cloning this repository, run: +- Be part of the conversation in the [dbt Community Slack](http://community.getdbt.com/) +- Read more on the [dbt Community Discourse](https://discourse.getdbt.com) -```bash -git submodule update --init --recursive -``` +## Reporting bugs and contributing code -You'll also need to install bundler if you don't already have it: -```bash -gem install bundler -bundle install -``` +- Want to report a bug or request a feature? Let us know and open [an issue](https://github.com/dbt-labs/dbt-docs/issues/new) +- Want to help us build dbt-docs? Check out the [Contributing Guide](https://github.com/dbt-labs/dbt-docs/blob/HEAD/CONTRIBUTING.md) -### Build / Run - -To build the css files required for webpack: - -```bash -cd styles -bundle exec jekyll build -cd - -``` - - -To build an index.html file: - -```bash -npm install -npx webpack -``` - -To run the dev server, first copy your `manifest.json` and `catalog.json` files to -the `src/` directory. Then run: +## Code of Conduct -```bash -npm install -npm start -``` +Everyone interacting in the dbt project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [dbt Code of Conduct](https://community.getdbt.com/code-of-conduct). From f223da0e40f86b9928b8fece5b2dd629d505cd09 Mon Sep 17 00:00:00 2001 From: Emily Rockman <emily.rockman@dbtlabs.com> Date: Wed, 6 Dec 2023 11:35:59 -0600 Subject: [PATCH 2/4] tweak contributing --- CONTRIBUTING.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4335705e..1d7c0d0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,6 @@ -** replace `dbt-docs` with your repository name in all docs - - # Contributing to `dbt-docs` -`dbt-docs` is a template for open source software projects at dbt Labs. - +`dbt-docs` contains code for generating a documentation site for dbt projects. 1. [About this document](#about-this-document) 2. [Getting the code](#getting-the-code) From 0349279f3e56e997144eafc99fef6b48ac6cb377 Mon Sep 17 00:00:00 2001 From: Emily Rockman <emily.rockman@dbtlabs.com> Date: Thu, 7 Dec 2023 09:21:51 -0600 Subject: [PATCH 3/4] add troubleshooting section --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d7c0d0b..de79c40e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ 6. [Debugging](#debugging) 7. [Adding or modifying a changelog entry](#adding-or-modifying-a-changelog-entry) 8. [Submitting a Pull Request](#submitting-a-pull-request) +9. [Troubleshooting Tips](#troubleshooting-tips) ## About this document @@ -110,4 +111,5 @@ Automated tests run via GitHub Actions. If you're a first-time contributor, all Once all tests are passing and your PR has been approved, a `dbt-docs` maintainer will merge your changes into the active development branch. And that's it! Happy developing :tada: -Sometimes, the content license agreement auto-check bot doesn't find a user's entry in its roster. If you need to force a rerun, add `@cla-bot check` in a comment on the pull request. +## Troubleshooting Tips +- Sometimes, the content license agreement auto-check bot doesn't find a user's entry in its roster. If you need to force a rerun, add `@cla-bot check` in a comment on the pull request. From 5a68479e058f9cd1b7ba2ecc3860055083ad64d7 Mon Sep 17 00:00:00 2001 From: Emily Rockman <emily.rockman@dbtlabs.com> Date: Thu, 7 Dec 2023 09:23:33 -0600 Subject: [PATCH 4/4] reword issue template --- .github/ISSUE_TEMPLATE/implementation-ticket.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/implementation-ticket.yml b/.github/ISSUE_TEMPLATE/implementation-ticket.yml index 2636d646..a3b052c4 100644 --- a/.github/ISSUE_TEMPLATE/implementation-ticket.yml +++ b/.github/ISSUE_TEMPLATE/implementation-ticket.yml @@ -52,7 +52,7 @@ body: attributes: label: Context description: | - Provide the "why", motivation, and alternative approaches considered -- linking to previous refinement issues, spikes, Notion docs as appropriate + Provide the "why", motivation, and alternative approaches considered -- linking to previous refinement issues, spikes, docs as appropriate validations: validations: required: false