OSS standardization changes

.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: "[<project>] <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

.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

.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"

CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to `dbt-docs`
+
+`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)
+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.

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).