|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -## Requirements |
4 | | - |
5 | | -* Python>=3.9 - [docs](https://www.python.org/) |
6 | | -* Hatch - [docs](https://hatch.pypa.io/dev/) |
7 | | - |
8 | | -## Getting started |
9 | | - |
10 | | -### Hatch |
11 | | - |
12 | | -This repository uses `hatch` as its primary development tool. |
13 | | -`hatch` will store its virtual environments in its own user space unless you configure it. |
14 | | -We strongly recommend that you configure `hatch` to store its virtual environments in an explicit location. |
15 | | -This has two benefits: |
16 | | - |
17 | | -* this path is predictable and easily discoverable, making it much easier to use with IDEs |
18 | | -* the default environment uses a hash for the name whereas the explicit environment will use |
19 | | -a predictable and human-readable name |
20 | | - |
21 | | -For example, we configure `hatch` to store its virtual environments in the project itself (first option below). |
22 | | -This is akin to running `python -m venv venv` from the project root. |
23 | | -Many folks prefer to store virtual environments in a central location separate from the project (second option below). |
24 | | - |
25 | | -```toml |
26 | | -# MacOS : ~/Library/Application Support/hatch/config.toml |
27 | | -# Windows : %USERPROFILE%\AppData\Local\hatch\config.toml |
28 | | -# Unix : ~.config/hatch/config.toml |
29 | | - |
30 | | -# this will create the virtual environment at `dbt-athena/dbt-athena/.hatch/dbt-athena |
31 | | -[dirs.env] |
32 | | -virtual = ".hatch" |
33 | | - |
34 | | -# this will create the virtual environment at `~/.hatch/dbt-athena` |
35 | | -[dirs.env] |
36 | | -virtual = "~/.hatch" |
37 | | -``` |
38 | | - |
39 | | -You can find the full docs [here](https://hatch.pypa.io/dev/config/hatch/) if you'd like to learn more about `hatch`. |
40 | | - |
41 | | -### Initial setup |
42 | | - |
43 | | -You will need to perform these steps the first time you contribute. |
44 | | -If you plan on contributing in the future (we would really appreciate that!), |
45 | | -most of this should persist and be reusable at that point in time. |
46 | | - |
47 | | -<!-- markdownlint-disable MD013 --> |
48 | | -* Fork the `dbt-athena` repo into your own user space on GitHub - [docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) |
49 | | -* Install `hatch` on your local machine - [docs](https://hatch.pypa.io/dev/install/) |
50 | | -* Clone the fork to your local machine - [docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) |
51 | | -* Navigate to the `dbt-athena` package directory |
52 | | - * There are two packages in this repository. Don't worry about `dbt-athena-community`, |
53 | | - it will automatically remain in sync with `dbt-athena` |
54 | | -* Setup your development environment with `hatch run setup`: |
55 | | - 1. Create a `hatch` virtual environment |
56 | | - 2. Install all dependencies |
57 | | - 3. Install pre-commit hooks |
58 | | - 4. Create a `test.env` stub file (formerly `.env`) |
59 | | -* Adjust the `test.env` file by configuring the environment variables to match your Athena development environment |
60 | | -<!-- markdownlint-restore --> |
61 | | - |
62 | | -```shell |
63 | | -# install `hatch` |
64 | | -pip install hatch |
65 | | - |
66 | | -# clone your fork |
67 | | -git clone https://github.com/<user>/dbt-athena |
68 | | - |
69 | | -# navigate to the dbt-athena package |
70 | | -cd dbt-athena |
71 | | - |
72 | | -# setup your development environment (formerly `make setup`) |
73 | | -hatch run setup |
74 | | -``` |
75 | | - |
76 | | -## Running tests and checks |
77 | | - |
78 | | -There are many checks that are collectively referred to as Code Quality checks as well as 2 different types of testing: |
79 | | - |
80 | | -* **code quality checks**: these checks include static analysis, type checking, and other code quality assurances |
81 | | -* **unit testing**: these tests are fast tests that don't require a platform connection |
82 | | -* **integration testing**: these tests are more thorough and require an AWS account with an Athena instance configured |
83 | | - * Details of the Athena instance also need to be configured in your `test.env` file |
84 | | - |
85 | | -These tests and checks can be run as follows: |
86 | | - |
87 | | -```shell |
88 | | -# run all pre-commit checks |
89 | | -hatch run code-quality |
90 | | - |
91 | | -# run unit tests (formerly `make unit_test`) |
92 | | -hatch run unit-tests |
93 | | - |
94 | | -# run integration tests (formerly `make integration_test`) |
95 | | -hatch run integration-tests |
96 | | - |
97 | | -# run unit tests and integration tests, formerly `make test` |
98 | | -hatch run all-tests |
99 | | - |
100 | | -# run specific integration tests |
101 | | -hatch run integration-tests tests/functional/my/test_file.py |
102 | | -``` |
103 | | - |
104 | | -## Submitting a pull request |
105 | | - |
106 | | -<!-- markdownlint-disable MD013 --> |
107 | | -* Create a commit with your changes and push them back up to your fork (e.g. `https://github.com/<user>/dbt-athena`) |
108 | | -* Create a [pull request](https://github.com/dbt-labs/dbt-athena/compare) on GitHub - [docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) |
109 | | - * The pull request title and commit messages should adhere to [conventional commits](https://www.conventionalcommits.org) |
110 | | - * The pull request body should describe _motivation_ |
111 | | -<!-- markdownlint-restore --> |
112 | | - |
113 | | -### General Guidelines |
114 | | - |
115 | | -* Keep your Pull Request small and focused on a single feature or bug fix |
116 | | -* Make sure your change is well tested |
117 | | - * Add new tests for completely new features or bug fixes |
118 | | - * Add scenarios to existing tests if extending a feature |
119 | | -* Make sure your change is well documented |
120 | | - * Mention when something is not obvious, or is being used for a specific purpose |
121 | | - * Provide a link to the GitHub bug in the docstring when writing a new test demonstrating the bug |
122 | | -* Provide a clear description in your pull request to allow the reviewer to understand the context of your changes |
123 | | - * Use a "self-review" to walk the reviewer through your thought process in a specific area |
124 | | - * Use a "self-review" to ask a question about how to handle a specific problem |
125 | | -* Use a draft pull request during development and mark it as Ready for Review when you're ready |
126 | | - * Ideally CI is also passing at this point, but you may also be looking for feedback on how to resolve an issue |
| 3 | +This repository has moved into [dbt-labs/dbt-adapters](https://www.github.com/dbt-labs/dbt-adapters). |
| 4 | +Please refer to that repo for a guide on how to contribute to `dbt-athena`. |
0 commit comments