From 3c8058ca566256cb9d366b872ab133dc324e97af Mon Sep 17 00:00:00 2001 From: evantahler Date: Mon, 12 Sep 2022 15:56:41 -0700 Subject: [PATCH 1/2] fix changelog formatting --- docs/docusaurus/locally_testing_docusaurus.md | 16 +++++++--------- docs/understanding-airbyte/airbyte-protocol.md | 18 +++++++++--------- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/docusaurus/locally_testing_docusaurus.md b/docs/docusaurus/locally_testing_docusaurus.md index 8e3f4a0a2434..4332e555dfb1 100644 --- a/docs/docusaurus/locally_testing_docusaurus.md +++ b/docs/docusaurus/locally_testing_docusaurus.md @@ -4,12 +4,12 @@ You can test any change you make to see how it will look in production -The processes are almost identical from local testing to production so +The processes are almost identical from local testing to production so you can have a high degree of confidence in the results ```bash # navigate to docusaurus -cd airbyte-cloud/docusaurus +cd docusaurus # install the packages to run docusaurus yarn install # compile the current state of airbyte-cloud/docs @@ -20,13 +20,11 @@ yarn build && yarn serve # to exit the running server use control-c ``` -- If you encounter a build error there may be multiple causes -but usually this is due to a broken link: - - fix your broken links and the build should work -- look at the changes you made locally, -if they look great commit and add a funny picture to the PR for karma (technically optional) +- If you encounter a build error there may be multiple causes + but usually this is due to a broken link: - fix your broken links and the build should work +- look at the changes you made locally, + if they look great commit and add a funny picture to the PR for karma (technically optional) **important note** if you run `yarn build && yarn serve` and make changes after that you will need -to exit the server using `control-c` from the command line and then running the -command `yarn build && yarn serve` again to see your new changes +to exit the server using `control-c` from the command line and then running the command `yarn build && yarn serve` again to see your new changes diff --git a/docs/understanding-airbyte/airbyte-protocol.md b/docs/understanding-airbyte/airbyte-protocol.md index b35193b60b0d..6e53c37d24c4 100644 --- a/docs/understanding-airbyte/airbyte-protocol.md +++ b/docs/understanding-airbyte/airbyte-protocol.md @@ -26,15 +26,15 @@ Each of these concepts is described in greater depth in their respective section The Airbyte Protocol is versioned independently of the Airbyte Platform, and the version number is used to determine the compatibility between connectors and the Airbyte Platform. -| Version | Date | Pull Request | Subject | -| :------ | :--------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | -| 0.3.0 | 2022-09-09 | [16479](https://github.com/airbytehq/airbyte/pull/16479) | `AirbyteLogMessage.stack_trace` added | -| 0.2.0 | 2022-06-10 | [13573](https://github.com/airbytehq/airbyte/pull/13573) and [12586](https://github.com/airbytehq/airbyte/pull/12586) | `STREAM` and `GLOBAL` STATE messages | -| 0.1.1 | 2022-06-06 | [13356](https://github.com/airbytehq/airbyte/pull/13356) | Add a namespace in association with the stream name | -| 0.1.0 | 2022-05-03 | [12458](https://github.com/airbytehq/airbyte/pull/12458) and [12581](https://github.com/airbytehq/airbyte/pull/12581) | `AirbyteTraceMessage` added to allow connectors to better communicate exceptions | -| 0.0.2 | 2021-11-15 | [7798](https://github.com/airbytehq/airbyte/pull/7798) | Support oAuth Connectors (internal) | -| 0.0.1 | 2021-11-19 | [1021](https://github.com/airbytehq/airbyte/pull/1021) | Remove sub-JSON Schemas | -| 0.0.0 | 2020-11-18 | [998](https://github.com/airbytehq/airbyte/pull/998) | Initial version described via JSON Schema | +| Version | Date of Change | Pull Request(s) | Subject | +| :------- | :------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------- | +| `v0.3.0` | 2022-09-09 | [16479](https://github.com/airbytehq/airbyte/pull/16479) | `AirbyteLogMessage.stack_trace` added | +| `v0.2.0` | 2022-06-10 | [13573](https://github.com/airbytehq/airbyte/pull/13573) & [12586](https://github.com/airbytehq/airbyte/pull/12586) | `STREAM` and `GLOBAL` STATE messages | +| `v0.1.1` | 2022-06-06 | [13356](https://github.com/airbytehq/airbyte/pull/13356) | Add a namespace in association with the stream name | +| `v0.1.0` | 2022-05-03 | [12458](https://github.com/airbytehq/airbyte/pull/12458) & [12581](https://github.com/airbytehq/airbyte/pull/12581) | `AirbyteTraceMessage` added to allow connectors to better communicate exceptions | +| `v0.0.2` | 2021-11-15 | [7798](https://github.com/airbytehq/airbyte/pull/7798) | Support oAuth Connectors (internal) | +| `v0.0.1` | 2021-11-19 | [1021](https://github.com/airbytehq/airbyte/pull/1021) | Remove sub-JSON Schemas | +| `v0.0.0` | 2020-11-18 | [998](https://github.com/airbytehq/airbyte/pull/998) | Initial version described via JSON Schema | ## Actor Interface From a7aa9a403f533b53424c61a44e8e79b49bc1ab4b Mon Sep 17 00:00:00 2001 From: evantahler Date: Mon, 12 Sep 2022 15:59:06 -0700 Subject: [PATCH 2/2] fixup docs --- docs/docusaurus/deploying_and_reverting_docs.md | 13 +++++-------- docs/docusaurus/locally_testing_docusaurus.md | 10 ++++------ 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/docusaurus/deploying_and_reverting_docs.md b/docs/docusaurus/deploying_and_reverting_docs.md index 4f1955c6315c..9efc45e1e12c 100644 --- a/docs/docusaurus/deploying_and_reverting_docs.md +++ b/docs/docusaurus/deploying_and_reverting_docs.md @@ -2,14 +2,13 @@ ![docs are fun](../assets/docs/docs.jpg) -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. +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. -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. +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. -[This is the deployment tool](https://github.com/airbytehq/airbyte/blob/master/tools/bin/deploy_docusaurus) -You will need a github ssh key, the tool will properly tell you if you don't have one though +[This is the deployment tool](https://github.com/airbytehq/airbyte/blob/master/tools/bin/deploy_docusaurus). You will need a github ssh key, the tool will properly tell you if you don't have one though At it's simplest just open the airbyte repo and run `./tools/bin/deploy_docusaurus` @@ -17,14 +16,13 @@ A typical deployment will look like this ```bash cd airbyte -# or cd airbyte-cloud +# or cd airbyte-cloud git checkout master git pull ./tools/bin/deploy_docusaurus ``` -If docs has a problem this procedure will work the same on older branches. -The push to production is a force push so collisions are unlikely +If docs has a problem this procedure will work the same on older branches. The push to production is a force push so collisions are unlikely If you want to revert/rollback it will look something like this @@ -35,4 +33,3 @@ git checkout $SOME_OLDER_BRANCH ``` 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/docs/docusaurus/locally_testing_docusaurus.md b/docs/docusaurus/locally_testing_docusaurus.md index 4332e555dfb1..9981acf039d1 100644 --- a/docs/docusaurus/locally_testing_docusaurus.md +++ b/docs/docusaurus/locally_testing_docusaurus.md @@ -20,11 +20,9 @@ yarn build && yarn serve # to exit the running server use control-c ``` -- If you encounter a build error there may be multiple causes - but usually this is due to a broken link: - fix your broken links and the build should work -- look at the changes you made locally, - if they look great commit and add a funny picture to the PR for karma (technically optional) +- If you encounter a build error there may be multiple causes but usually this is due to a broken link: + - fix your broken links and the build should work +- look at the changes you made locally, if they look great commit and add a funny picture to the PR for karma (technically optional) **important note** -if you run `yarn build && yarn serve` and make changes after that you will need -to exit the server using `control-c` from the command line and then running the command `yarn build && yarn serve` again to see your new changes +if you run `yarn build && yarn serve` and make changes after that you will need to exit the server using `control-c` from the command line and then running the command `yarn build && yarn serve` again to see your new changes