You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contributing-to-airbyte/code-style.md
+12Lines changed: 12 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -32,3 +32,15 @@ Install it in IntelliJ:
32
32
5.`Add final modifier to local variable or parameter` > check the box
33
33
6. Apply the changes
34
34
7. You're done!
35
+
36
+
## Source code comments
37
+
38
+
It's hard to pin down exactly what to do around source code comments, but there are two \(very subjective\) and rough guidelines:
39
+
40
+
**If something is not obvious, write it down**. Examples include:
41
+
42
+
* non-trivial class definitions should have docstrings
43
+
* magic variables should have comments explaining why those values are used \(e.g: if using a page size of 10 in a connector, describe why if possible. If there is no reason, that's also fine, just mention in a comment\).
44
+
* Complicated subroutines/logic which cannot be refactored should have comments explaining what they are doing and why
45
+
46
+
**If something is obvious, don't write it down** since it's probably more likely to go out of date. For example, a comment like `x = 42; // sets x to 42` is not adding any new information and is therefore better omitted.
**Describe outputs, not implementation**: An issue or PR title should describe the desired end result, not the implementation. The exception is child issues/subissues of an epic. **Be specific about the domain**. Airbyte operates a monorepo, so being specific about what is being changed in the PR or issue title is important.
6
+
7
+
Some examples: _subpar issue title_: `Remove airbyteCdk.dependsOn("unrelatedPackage")`. This describes a solution not a problem.
8
+
9
+
_good issue title_: `Building the Airbyte Python CDK should not build unrelated packages`. Describes desired end state and the intent is understandable without reading the full issue.
10
+
11
+
_subpar PR title_: `Update tests`. Which tests? What was the update?
12
+
13
+
_good PR title_: `Source MySQL: update acceptance tests to connect to SSL-enabled database`. Specific about the domain and change that was made.
14
+
15
+
**PR title conventions** When creating a PR, follow the naming conventions depending on the change being made:
16
+
17
+
* Notable updates to Airbyte Core: "🎉"
18
+
* e.g: `🎉 enable configuring un-nesting in normalization`
19
+
* New connectors: “🎉 New source or destination: ” e.g: `🎉 New Source: Okta`
20
+
* New connector features: “🎉 : E.g:
21
+
*`🎉 Destination Redshift: write JSONs as SUPER type instead of VARCHAR`
22
+
*`🎉 Source MySQL: enable logical replication`
23
+
* Bugfixes should start with the 🐛 emoji
24
+
*`🐛 Source Facebook Marketing: fix incorrect parsing of lookback window`
25
+
* Documentation improvements should start with any of the book/paper emojis: 📚 📝 etc…
26
+
* Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis
27
+
28
+
The emojis help us identify which commits should be included in the product release notes.
29
+
30
+
## Descriptions
31
+
32
+
**Context**: Provide enough information \(or a link to enough information\) in the description so team members with no context can understand what the issue or PR is trying to accomplish. This usually means you should include two things:
33
+
34
+
1. Some background information motivating the problem
35
+
2. A description of the problem itself
36
+
3. Good places to start reading and file changes that can be skipped
37
+
38
+
Some examples:
39
+
40
+
_insufficient context_: `Create an OpenAPI to JSON schema generator`. Unclear what the value or problem being solved here is.
41
+
42
+
_good context_:
43
+
44
+
```text
45
+
When creating or updating connectors, we spend a lot of time manually transcribing JSON Schema files based on OpenAPI docs. This is ncessary because OpenAPI and JSON schema are very similar but not perfectly compatible. This process is automatable. Therefore we should create a program which converts from OpenAPI to JSONSchema format.
Documentation is written as [Markdown](https://guides.github.com/features/mastering-markdown/) files and stored in our Github repository.
3
+
We welcome contributions to the Airbyte documentation!
4
4
5
-
## Workflow for updating docs
5
+
Our docs is written in [Markdown](https://guides.github.com/features/mastering-markdown/) following the [Google developer documentation style guide](https://developers.google.com/style/highlights) and the files are stored in our [Github repository](https://github.com/airbytehq/airbyte/tree/master/docs). The docs are published at [docs.airbyte.com](https://docs.airbyte.com/) using [Docusaurus](https://docusaurus.io/) and [GitHub Pages](https://pages.github.com/).
6
6
7
-
1. Modify docs using Git or the Github UI \(All docs live in the `docs/` folder in the [Airbyte repository](https://github.com/airbytehq/airbyte)\)
8
-
2. If you're adding new files, update `docs/SUMMARY.md`.
9
-
3. Create a Pull Request
7
+
## Finding good first issues
10
8
11
-
### Sidebar updates
12
-
To edit the sidebar you must [edit this JSON in this Javascript file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js).
9
+
The Docs team maintains a list of [#good-first-issues](https://github.com/airbytehq/airbyte/issues?q=is%3Aopen+is%3Aissue+label%3Aarea%2Fdocumentation+label%3A%22good+first+issue%22) for new contributors.
13
10
14
-
### Modify in the Github UI
11
+
- If you're new to technical writing, start with the smaller issues (fixing typos, broken links, spelling and grammar, and so on). You can [edit the files directly on GitHub](#editing-directly-on-github).
12
+
- If you're an experienced technical writer or a developer interested in technical writing, comment on an issue that interests you to discuss it with the Docs team. Once we decide on the approach and the tasks involved, [edit the files and open a Pull Request](#editing-on-your-local-machine) for the Docs team to review.
15
13
16
-
1. Directly edit the docs you want to edit [in the Github UI](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository)
17
-
2. Create a Pull Request
14
+
## Contributing to Airbyte docs
18
15
19
-
### Modify using Git
16
+
Before contributing to Airbyte docs, read the Airbyte Community [Code of Conduct](code-of-conduct.md)
20
17
21
-
1.[Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repository.
22
-
2. Clone the fork on your workstation:
18
+
:::tip
19
+
If you're new to GitHub and Markdown, complete [the First Contributions tutorial](https://github.com/firstcontributions/first-contributions) and learn [Markdown basics](https://guides.github.com/features/mastering-markdown/) before contributing to Airbyte documentation.
20
+
:::
21
+
22
+
You can contribute to Airbyte docs in two ways:
23
+
24
+
### Editing directly on GitHub
25
+
26
+
To make minor changes (example: fixing typos) or edit a single file, you can edit the file directly on GitHub:
27
+
28
+
1. Click **Edit this page** at the bottom of any published document on [docs.airbyte.com](https://docs.airbyte.com/). You'll be taken to the GitHub editor.
29
+
2.[Edit the file directly on GitHub and open a Pull Request](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files).
30
+
31
+
### Editing on your local machine
32
+
33
+
To make complex changes or edit multiple files, edit the files on your local machine:
34
+
35
+
1.[Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the Airbyte [repository](https://github.com/airbytehq/airbyte).
@@ -35,124 +49,78 @@ To edit the sidebar you must [edit this JSON in this Javascript file](https://gi
35
49
36
50
While cloning on Windows, you might encounter errors about long filenames. Refer to the instructions [here](../deploying-airbyte/local-deployment.md#handling-long-filename-error) to correct it.
37
51
38
-
3. Modify the documentation.
39
-
4. Create a pull request
40
-
41
-
### Testing Changes
42
-
* You can run a copy of the website locally to test how your changes will look in production
43
-
* This is not necessary for smaller changes, but is suggested for large changes and **any** change to the sidebar, as the JSON will blow up if we misplace a comma.
44
-
* You will need [yarn](https://yarnpkg.com) installed locally to build docusaurus
45
-
* Run the following commands
46
-
```bash
47
-
cd docusaurus
48
-
yarn install
49
-
yarn build
50
-
yarn serve
51
-
```
52
-
53
-
You can now navigate to [http://localhost:3000/](http://localhost:3000/) to see your changes. You can stop the running server in OSX/Linux by pressing `control-c` in the terminal running the server
54
-
55
-
### Deploying the docs website
56
-
We use Github Pages for hosting this docs website, and Docusaurus as the docs framework. An [internal guide for deployment lives here](../docusaurus/deploying_and_reverting_docs.md).
57
-
58
-
The source code for the docs lives in the [airbyte monorepo's `docs/` directory](https://github.com/airbytehq/airbyte/tree/master/docs). To publish the updated docs on this website after you've committed a change to the `docs/` markdown files, it is required to locally run a manual publish flow. Locally run `./tools/bin/deploy_docusaurus` from the `airbyte` monorepo project root to deploy this docs website.
59
-
60
-
Automating this process via CI is currently not easy because we push to a [dedicated repo hosting the Github pages](https://airbytehq.github.io) from the `airbyte` monorepo, which is hard to do in CI. This is not intended to be the end state (we will need to publish these docs via CI eventually), but as of May 2022 have decided the juice isn't worth the squeeze just yet.
61
-
62
-
## Documentation Best Practices
63
-
64
-
Connectors typically have the following documentation elements:
52
+
3. Test changes locally:
65
53
66
-
* READMEs
67
-
* Changelogs
68
-
* Github Issues & Pull Requests
69
-
* Source code comments
70
-
* How-to guides
54
+
Run the following commands in your terminal:
71
55
72
-
Below are some best practices related to each of these.
56
+
```bash
57
+
cd docusaurus
58
+
yarn install
59
+
yarn build
60
+
yarn serve
61
+
```
62
+
Then navigate to [http://localhost:3000/](http://localhost:3000/) to see your changes. You can stop the running server in OSX/Linux by pressing `Ctrl-C` in the terminal.
73
63
74
-
### READMEs
64
+
4.[Follow the GitHub workflow](https://docs.github.com/en/get-started/quickstart/contributing-to-projects/) to edit the files and create a pull request.
75
65
76
-
Every module should have a README containing:
66
+
:::note
67
+
Before we accept any contributions, you'll need to sign the Contributor License Agreement (CLA). By signing a CLA, we can ensure that the community is free and confident in its ability to use your contributions. You will be prompted to sign the CLA while opening a pull request.
68
+
:::
77
69
78
-
* A brief description of the module
79
-
* development pre-requisites \(like which language or binaries are required for development\)
80
-
* how to install dependencies
81
-
* how to build and run the code locally & via Docker
82
-
* any other information needed for local iteration
70
+
5. Assign `airbytehq/docs` as a Reviewer for your pull request.
83
71
84
-
### Changelogs
72
+
##Additional guidelines
85
73
86
-
**Core**
74
+
- If you're updating a connector doc, follow the [Connector documentation template](https://hackmd.io/Bz75cgATSbm7DjrAqgl4rw)
75
+
- If you're adding a new file, update the [sidebars.js file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js)
76
+
- If you're adding a README to a code module, make sure the README has the following components:
77
+
- A brief description of the module
78
+
- Development pre-requisites (like which language or binaries are required for development)
79
+
- How to install dependencies
80
+
- How to build and run the code locally & via Docker
81
+
- Any other information needed for local iteration
87
82
88
-
Core changelogs should be updated in the `docs/project-overview/platform.md` file.
83
+
## Advanced tasks
89
84
90
-
#### Connectors
85
+
###Adding a redirect
91
86
92
-
Each connector should have a CHANGELOG.md section in its public facing docs in the `docs/integrations/<sources OR destinations>/<name>` at the bottom of the page. Inside, each new connector version should have a section whose title is the connector's version number. The body of this section should describe the changes added in the new version. For example:
87
+
To add a redirect, open the [`docusaurus.config.js`](https://github.com/airbytehq/airbyte/blob/master/docusaurus/docusaurus.config.js#L22) file and locate the following commented section:
93
88
94
-
```text
95
-
| Version | Date| Pull Request | Subject |
96
-
| :------ | :-------- | :-----| :------ |
97
-
| 0.2.0| 20XX-05-XX | [PR2#](https://github.com/airbytehq/airbyte/pull/PR2#) | Fixed bug with schema generation <br/><br/> Added a better description for the `password` input parameter |
Copy this section, replace the values, and [test the changes locally](#editing-on-your-local-machine) by going to the path you created a redirect for and verify that the address changes to the new one.
102
97
103
-
It's hard to pin down exactly what to do around source code comments, but there are two \(very subjective\) and rough guidelines:
98
+
:::note
99
+
Your path **needs* a leading slash `/` to work
100
+
:::
104
101
105
-
**If something is not obvious, write it down**. Examples include:
102
+
### Deploying and reverting the documentation site
106
103
107
-
* non-trivial class definitions should have docstrings
108
-
* magic variables should have comments explaining why those values are used \(e.g: if using a page size of 10 in a connector, describe why if possible. If there is no reason, that's also fine, just mention in a comment\).
109
-
* Complicated subroutines/logic which cannot be refactored should have comments explaining what they are doing and why
104
+
:::note
105
+
Only the Airbyte team and maintainers have permissions to deploy the documentation site.
106
+
:::
110
107
111
-
**If something is obvious, don't write it down** since it's probably more likely to go out of date. For example, a comment like `x = 42; // sets x to 42` is not adding any new information and is therefore better omitted.
108
+
You'll need a GitHub SSH key to deploy the documentation site using the [deployment tool](https://github.com/airbytehq/airbyte/blob/master/tools/bin/deploy_docusaurus).
112
109
113
-
### Issues & Pull Requests
110
+
To deploy the documentation site, run:
114
111
115
-
#### Titles
116
-
117
-
**Describe outputs, not implementation**: An issue or PR title should describe the desired end result, not the implementation. The exception is child issues/subissues of an epic. **Be specific about the domain**. Airbyte operates a monorepo, so being specific about what is being changed in the PR or issue title is important.
118
-
119
-
Some examples: _subpar issue title_: `Remove airbyteCdk.dependsOn("unrelatedPackage")`. This describes a solution not a problem.
120
-
121
-
_good issue title_: `Building the Airbyte Python CDK should not build unrelated packages`. Describes desired end state and the intent is understandable without reading the full issue.
122
-
123
-
_subpar PR title_: `Update tests`. Which tests? What was the update?
124
-
125
-
_good PR title_: `Source MySQL: update acceptance tests to connect to SSL-enabled database`. Specific about the domain and change that was made.
126
-
127
-
**PR title conventions** When creating a PR, follow the naming conventions depending on the change being made:
128
-
129
-
* Notable updates to Airbyte Core: "🎉"
130
-
* e.g: `🎉 enable configuring un-nesting in normalization`
131
-
* New connectors: “🎉 New source or destination: ” e.g: `🎉 New Source: Okta`
132
-
* New connector features: “🎉 : E.g:
133
-
*`🎉 Destination Redshift: write JSONs as SUPER type instead of VARCHAR`
134
-
*`🎉 Source MySQL: enable logical replication`
135
-
* Bugfixes should start with the 🐛 emoji
136
-
*`🐛 Source Facebook Marketing: fix incorrect parsing of lookback window`
137
-
* Documentation improvements should start with any of the book/paper emojis: 📚 📝 etc…
138
-
* Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis
139
-
140
-
The emojis help us identify which commits should be included in the product release notes.
141
-
142
-
#### Descriptions
143
-
144
-
**Context**: Provide enough information \(or a link to enough information\) in the description so team members with no context can understand what the issue or PR is trying to accomplish. This usually means you should include two things:
145
-
146
-
1. Some background information motivating the problem
147
-
2. A description of the problem itself
148
-
3. Good places to start reading and file changes that can be skipped
149
-
150
-
Some examples:
151
-
152
-
_insufficient context_: `Create an OpenAPI to JSON schema generator`. Unclear what the value or problem being solved here is.
112
+
```bash
113
+
cd airbyte
114
+
# or cd airbyte-cloud
115
+
git checkout master
116
+
git pull
117
+
./tools/bin/deploy_docusaurus
118
+
```
153
119
154
-
_good context_:
120
+
To revert/rollback doc changes, run:
155
121
156
-
```text
157
-
When creating or updating connectors, we spend a lot of time manually transcribing JSON Schema files based on OpenAPI docs. This is ncessary because OpenAPI and JSON schema are very similar but not perfectly compatible. This process is automatable. Therefore we should create a program which converts from OpenAPI to JSONSchema format.
Copy file name to clipboardExpand all lines: docs/docusaurus/deploying_and_reverting_docs.md
+5-3Lines changed: 5 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,9 @@
2
2
3
3
4
4
5
-
Docusaurus has a strange deployment pattern. Luckily that pattern is abstracted away from you.
5
+
We use Github Pages for hosting this docs website, and Docusaurus as the docs framework. Docusaurus has a strange deployment pattern. Luckily that pattern is abstracted away from you.
6
6
7
-
If you were looking for the contribution guide [check this doc out](contributing_to_docs.md)
7
+
The source code for the docs lives in the [airbyte monorepo's `docs/` directory](https://github.com/airbytehq/airbyte/tree/master/docs). To publish the updated docs on this website after you've committed a change to the `docs/` markdown files, it is required to locally run a manual publish flow.
8
8
9
9
Docs will deploy from whatever branch you are in. You will probably want to deploy from master, but that is at your discretion.
10
10
@@ -15,7 +15,6 @@ At it's simplest just open the airbyte repo and run `./tools/bin/deploy_docusaur
15
15
16
16
A typical deployment will look like this
17
17
18
-
19
18
```bash
20
19
cd airbyte
21
20
# or cd airbyte-cloud
@@ -34,3 +33,6 @@ cd airbyte
34
33
git checkout $SOME_OLDER_BRANCH
35
34
./tools/bin/deploy_docusaurus
36
35
```
36
+
37
+
Automating this process via CI is currently not easy because we push to a [dedicated repo hosting the Github pages](https://airbytehq.github.io) from the `airbyte` monorepo, which is hard to do in CI. This is not intended to be the end state (we will need to publish these docs via CI eventually), but as of May 2022 have decided the juice isn't worth the squeeze just yet.
0 commit comments