Updated the docs contribution guide (#15619)

* Initial changes * more edits
airbytehq · Aug 12, 2022 · 3c9c5d4 · 3c9c5d4
1 parent b0d1317
commit 3c9c5d4
Show file tree

Hide file tree

Showing 5 changed files with 149 additions and 125 deletions.
diff --git a/docs/contributing-to-airbyte/code-style.md b/docs/contributing-to-airbyte/code-style.md
@@ -32,3 +32,15 @@ Install it in IntelliJ:
          5. `Add final modifier to local variable or parameter` > check the box
          6. Apply the changes
 7. You're done!
+
+## Source code comments
+
+It's hard to pin down exactly what to do around source code comments, but there are two \(very subjective\) and rough guidelines:
+
+**If something is not obvious, write it down**. Examples include:
+
+* non-trivial class definitions should have docstrings
+* 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\).
+* Complicated subroutines/logic which cannot be refactored should have comments explaining what they are doing and why
+
+**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.
diff --git a/docs/contributing-to-airbyte/issues-and-pull-requests.md b/docs/contributing-to-airbyte/issues-and-pull-requests.md
@@ -0,0 +1,46 @@
+# Issues & Pull Requests
+
+## Titles
+
+**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.
+
+Some examples: _subpar issue title_: `Remove airbyteCdk.dependsOn("unrelatedPackage")`. This describes a solution not a problem.
+
+_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.
+
+_subpar PR title_: `Update tests`. Which tests? What was the update?
+
+_good PR title_: `Source MySQL: update acceptance tests to connect to SSL-enabled database`. Specific about the domain and change that was made.
+
+**PR title conventions** When creating a PR, follow the naming conventions depending on the change being made:
+
+* Notable updates to Airbyte Core: "🎉"
+  * e.g: `🎉 enable configuring un-nesting in normalization`
+* New connectors: “🎉 New source or destination: ” e.g: `🎉 New Source: Okta`
+* New connector features: “🎉 :  E.g:
+  * `🎉 Destination Redshift: write JSONs as SUPER type instead of VARCHAR`
+  * `🎉 Source MySQL: enable logical replication`
+* Bugfixes should start with the  🐛 emoji
+  * `🐛 Source Facebook Marketing: fix incorrect parsing of lookback window`
+* Documentation improvements should start with any of the book/paper emojis: 📚 📝 etc…
+* Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis
+
+The emojis help us identify which commits should be included in the product release notes.
+
+## Descriptions
+
+**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:
+
+1. Some background information motivating the problem
+2. A description of the problem itself
+3. Good places to start reading and file changes that can be skipped
+
+   Some examples:
+
+_insufficient context_: `Create an OpenAPI to JSON schema generator`. Unclear what the value or problem being solved here is.
+
+_good context_:
+
+```text
+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.
+```
diff --git a/docs/contributing-to-airbyte/updating-documentation.md b/docs/contributing-to-airbyte/updating-documentation.md
@@ -1,25 +1,39 @@
 # Updating Documentation
 
-Documentation is written as [Markdown](https://guides.github.com/features/mastering-markdown/) files and stored in our Github repository.
+We welcome contributions to the Airbyte documentation! 
 
-## Workflow for updating docs
+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/). 
 
-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)\)
-2. If you're adding new files, update `docs/SUMMARY.md`.
-3. Create a Pull Request
+## Finding good first issues
 
-### Sidebar updates
-To edit the sidebar you must [edit this JSON in this Javascript file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js).
+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. 
 
-### Modify in the Github UI
+- 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).
+- 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.
 
-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)
-2. Create a Pull Request
+## Contributing to Airbyte docs
 
-### Modify using Git
+Before contributing to Airbyte docs, read the Airbyte Community [Code of Conduct](code-of-conduct.md)
 
-1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repository.
-2. Clone the fork on your workstation:
+:::tip
+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. 
+:::
+
+You can contribute to Airbyte docs in two ways:
+
+### Editing directly on GitHub
+
+To make minor changes (example: fixing typos) or edit a single file, you can edit the file directly on GitHub:
+
+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. 
+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).
+
+### Editing on your local machine
+
+To make complex changes or edit multiple files, edit the files on your local machine:
+
+1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the Airbyte [repository](https://github.com/airbytehq/airbyte).
+2. Clone the fork on your local machine:
 
    ```bash
    git clone git@github.com:{YOUR_USERNAME}/airbyte.git
@@ -35,124 +49,78 @@ To edit the sidebar you must [edit this JSON in this Javascript file](https://gi
 
    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.
 
-3. Modify the documentation.
-4. Create a pull request
-
-### Testing Changes
-* You can run a copy of the website locally to test how your changes will look in production
-* 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.
-* You will need [yarn](https://yarnpkg.com) installed locally to build docusaurus
-* Run the following commands
-```bash
-cd docusaurus
-yarn install
-yarn build
-yarn serve
-```
-
-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
-
-### Deploying the docs website
-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).
-
-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.
-
-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.
-
-## Documentation Best Practices
-
-Connectors typically have the following documentation elements:
+3. Test changes locally: 
 
-* READMEs
-* Changelogs
-* Github Issues & Pull Requests
-* Source code comments
-* How-to guides
+  Run the following commands in your terminal:
 
-Below are some best practices related to each of these.
+  ```bash
+  cd docusaurus
+  yarn install
+  yarn build
+  yarn serve
+  ```
+  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.
 
-### READMEs
+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.
 
-Every module should have a README containing:
+    :::note
+    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.
+    :::
 
-* A brief description of the module
-* development pre-requisites \(like which language or binaries are required for development\)
-* how to install dependencies
-* how to build and run the code locally & via Docker
-* any other information needed for local iteration
+5. Assign `airbytehq/docs` as a Reviewer for your pull request. 
 
-### Changelogs
+## Additional guidelines
 
-**Core**
+- If you're updating a connector doc, follow the [Connector documentation template](https://hackmd.io/Bz75cgATSbm7DjrAqgl4rw)
+- If you're adding a new file, update the [sidebars.js file](https://github.com/airbytehq/airbyte/blob/master/docusaurus/sidebars.js)
+- If you're adding a README to a code module, make sure the README has the following components:
+    - A brief description of the module
+    - Development pre-requisites (like which language or binaries are required for development)
+    - How to install dependencies
+    - How to build and run the code locally & via Docker
+    - Any other information needed for local iteration
 
-Core changelogs should be updated in the `docs/project-overview/platform.md` file.
+## Advanced tasks 
 
-#### Connectors
+### Adding a redirect
 
-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:
+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:
 
-```text
-| Version | Date       | Pull Request | Subject |
-| :------ | :--------  | :-----       | :------ |
-| 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 |
-| 0.1.0   | 20XX-04-XX | [PR#](https://github.com/airbytehq/airbyte/pull/PR#) | Added incremental sync |
+```js
+//                        {
+//                         from: '/some-lame-path',
+//                         to: '/a-much-cooler-uri',
+//                        },
 ```
 
-### Source code comments
+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.
 
-It's hard to pin down exactly what to do around source code comments, but there are two \(very subjective\) and rough guidelines:
+:::note 
+Your path **needs* a leading slash `/` to work
+:::
 
-**If something is not obvious, write it down**. Examples include:
+### Deploying and reverting the documentation site
 
-* non-trivial class definitions should have docstrings
-* 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\).
-* Complicated subroutines/logic which cannot be refactored should have comments explaining what they are doing and why
+:::note
+Only the Airbyte team and maintainers have permissions to deploy the documentation site.
+:::
 
-**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.
+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). 
 
-### Issues & Pull Requests
+To deploy the documentation site, run:
 
-#### Titles
-
-**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.
-
-Some examples: _subpar issue title_: `Remove airbyteCdk.dependsOn("unrelatedPackage")`. This describes a solution not a problem.
-
-_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.
-
-_subpar PR title_: `Update tests`. Which tests? What was the update?
-
-_good PR title_: `Source MySQL: update acceptance tests to connect to SSL-enabled database`. Specific about the domain and change that was made.
-
-**PR title conventions** When creating a PR, follow the naming conventions depending on the change being made:
-
-* Notable updates to Airbyte Core: "🎉"
-  * e.g: `🎉 enable configuring un-nesting in normalization`
-* New connectors: “🎉 New source or destination: ” e.g: `🎉 New Source: Okta`
-* New connector features: “🎉 :  E.g:
-  * `🎉 Destination Redshift: write JSONs as SUPER type instead of VARCHAR`
-  * `🎉 Source MySQL: enable logical replication`
-* Bugfixes should start with the  🐛 emoji
-  * `🐛 Source Facebook Marketing: fix incorrect parsing of lookback window`
-* Documentation improvements should start with any of the book/paper emojis: 📚 📝 etc…
-* Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis
-
-The emojis help us identify which commits should be included in the product release notes.
-
-#### Descriptions
-
-**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:
-
-1. Some background information motivating the problem
-2. A description of the problem itself
-3. Good places to start reading and file changes that can be skipped
-
-   Some examples:
-
-_insufficient context_: `Create an OpenAPI to JSON schema generator`. Unclear what the value or problem being solved here is.
+```bash
+cd airbyte
+# or cd airbyte-cloud  
+git checkout master
+git pull
+./tools/bin/deploy_docusaurus
+```
 
-_good context_:
+To revert/rollback doc changes, run:
 
-```text
-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.
+```
+cd airbyte
+git checkout <OLDER_BRANCH>
+./tools/bin/deploy_docusaurus
 ```
diff --git a/docs/docusaurus/deploying_and_reverting_docs.md b/docs/docusaurus/deploying_and_reverting_docs.md
@@ -2,9 +2,9 @@
 
 ![docs are fun](../assets/docs/docs.jpg)
 
-Docusaurus has a strange deployment pattern.  Luckily that pattern is abstracted away from you.
+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.
 
-If you were looking for the contribution guide [check this doc out](contributing_to_docs.md)
+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. 
 
 Docs will deploy from whatever branch you are in. You will probably want to deploy from master, but that is at your discretion.
 
@@ -15,7 +15,6 @@ At it's simplest just open the airbyte repo and run `./tools/bin/deploy_docusaur
 
 A typical deployment will look like this
 
-
 ```bash
 cd airbyte
 # or cd airbyte-cloud  
@@ -34,3 +33,6 @@ cd airbyte
 git checkout $SOME_OLDER_BRANCH
 ./tools/bin/deploy_docusaurus
 ```
+
+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.
+
diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js
@@ -224,13 +224,9 @@ module.exports = {
         'contributing-to-airbyte/developing-on-kubernetes',
         'contributing-to-airbyte/monorepo-python-development',
         'contributing-to-airbyte/code-style',
+        'contributing-to-airbyte/issues-and-pull-requests',
         'contributing-to-airbyte/gradle-cheatsheet',
         'contributing-to-airbyte/gradle-dependency-update',
-        {
-          type: 'link',
-          label: 'Connector template',
-          href: 'https://hackmd.io/Bz75cgATSbm7DjrAqgl4rw',
-        },
         {
           type: 'category',
           label: 'Updating documentation',
@@ -239,11 +235,11 @@ module.exports = {
             id: 'contributing-to-airbyte/updating-documentation',
           },
           items: [
-            'docusaurus/contributing_to_docs',
-            'docusaurus/making_a_redirect',
-            'docusaurus/deploying_and_reverting_docs',
-            'docusaurus/locally_testing_docusaurus',
-            'docusaurus/readme',
+            {
+              type: 'link',
+              label: 'Connector doc template',
+              href: 'https://hackmd.io/Bz75cgATSbm7DjrAqgl4rw',
+            },
           ]
         },
       ]