From 6e7779a19269f5f78a6a89b3971b81bf8f9f8a39 Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 12:30:31 -0500 Subject: [PATCH 1/7] Build new structure for docs --- docs/api.mdx | 109 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/intro.mdx | 106 +---------------------------------------------- 2 files changed, 110 insertions(+), 105 deletions(-) create mode 100644 docs/api.mdx diff --git a/docs/api.mdx b/docs/api.mdx new file mode 100644 index 0000000..b0cc253 --- /dev/null +++ b/docs/api.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 2 +--- + +import GitHubLogo from "../static/logos/github.svg"; +import GitLabLogo from "../static/logos/gitlab.svg"; +import BitbucketLogo from "../static/logos/bitbucket.svg"; +import JiraLogo from "../static/logos/jira.svg"; +import ConfluenceLogo from "../static/logos/confluence.svg"; +import NotionLogo from "../static/logos/notion.svg"; +import SlackLogo from "../static/logos/slack.svg"; +import LinearLogo from "../static/logos/linear.svg"; + +# Watermelon API + +We try to keep the API as simple as possible, and we currently offer only 3 endpoints. We will return the full context taking into consideration the user's connected services and their settings. + +## Actions + +To be used to comment from GitHub, not currently open. +This endpoint will write a comment to the PR. + +### Context + +Will return the whole context as a Markdown Comment in the PR. + +## Extension + +To be used from the IDEs. + +### Hover + +Will return a list of single element hits for the connected services. Does _not_ return an AI summary. + +### Context + +Recieves: + +```js +{ + email: string, + gitSystem: "github"| "gitlab"| "bitbucket", + repo: string, + owner: string, + commitList: string[] +} +``` + +Returns an array of services that contain the same information. + +```js +{ + [serviceName]: { + title: string; + body?: string; + link?: string; + number?: number | string; + image?: string; + }[] +} +``` + +## Services + +The current supported list of services is: + + diff --git a/docs/intro.mdx b/docs/intro.mdx index f268222..87128dd 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -2,108 +2,4 @@ sidebar_position: 1 --- -import GitHubLogo from "../static/logos/github.svg"; -import GitLabLogo from "../static/logos/gitlab.svg"; -import BitbucketLogo from "../static/logos/bitbucket.svg"; -import JiraLogo from "../static/logos/jira.svg"; -import ConfluenceLogo from "../static/logos/confluence.svg"; -import NotionLogo from "../static/logos/notion.svg"; -import SlackLogo from "../static/logos/slack.svg"; -import LinearLogo from "../static/logos/linear.svg"; - -# Watermelon API - -We try to keep the API as simple as possible, and we currently offer only 3 endpoints. We will return the full context taking into consideration the user's connected services and their settings. - -## Actions - -To be used to comment from GitHub, not currently open. -This endpoint will write a comment to the PR. - -### Context - -Will return the whole context as a Markdown Comment in the PR. - -## Extension - -To be used from the IDEs. - -### Hover - -Will return a list of single element hits for the connected services. Does _not_ return an AI summary. - -### Context - -Recieves: - -```js -{ - email: string, - gitSystem: "github"| "gitlab"| "bitbucket", - repo: string, - owner: string, - commitList: string[] -} -``` - -Returns an array of services that contain the same information. - -```js -{ - [serviceName]: { - title: string; - body?: string; - link?: string; - number?: number | string; - image?: string; - }[] -} -``` - -## Services - -The current supported list of services is: - - +# Watermelon Docs \ No newline at end of file From 2426de535a22424ea18b4fc2e36fde2b28de02fe Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 15:13:41 -0500 Subject: [PATCH 2/7] Create the about page --- docs/about.mdx | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/intro.mdx | 7 ++++- 2 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/about.mdx diff --git a/docs/about.mdx b/docs/about.mdx new file mode 100644 index 0000000..fcc1250 --- /dev/null +++ b/docs/about.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 2 +--- + +# Watermelon Overview + +## Introduction +Watermelon's mission is to help software engineering teams deliver code that meets the business requirements faster. + +For software engineering teams that spend a lot of time discussing which variation of their code is the one that generates the most value for the user, Watermelon provides a set of [open-source plug-ins](https://github.com/watermelontools) to enrich the code review process with business logic contextualization. + +To do this we're building an **open-source passive documentation search engine** that serves both our IDE extensions (we currently support VS Code and IntelliJ) as well as our GitHub application (we will support more version control systems in the near future). + +## What is passive documentation? +According to Silona Bonewald (former Director of InnerSource Commons), *“Passive documentation is the record of the documentation we create every day while communicating openly.”* For example, as you talk about code in systems such as GitHub Pull Requests, Slack message threads, Linear tickets or Confluence pages, you’re creating passive documentation. + +Historically, open-source software has this very well figured out. Hundreds of people distributed across the globe can collaborate on a project because all the context and rationale for decisions are documented passively through conversations on GitHub, mailing lists, IRC, etc. We want to bring those benefits to private software teams. As a codebase and the customer base of a product grows its codebase grows, its business requirements grow and its need for the findability of passive documentation grows as well. + +## Watermelon in your workflow +Watermelon is available both as an IDE plugin and as a GitHub app. To get started with one of our IDE extensions, you don't need to authenticate to additional services (although it's highly encouraged). To work on your CI/CD, you need to authorize Watermelon on your GitHub organization (additional services are optional but highly encouraged). + +The current supported list of services is: + + + + +### Improve this documentation +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/intro.mdx b/docs/intro.mdx index 87128dd..94875e1 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -2,4 +2,9 @@ sidebar_position: 1 --- -# Watermelon Docs \ No newline at end of file +# Welcome to Watermelon Documentation + +Use the examples reference documentation to learn how to use Watermelon's suite of products. + +This documentation is open source. To contribute, please check out the [GitHub repo](https://github.com/watermelontools/docs). + From c8f803620032310b89303324496ee30a90a6c0fe Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 15:15:27 -0500 Subject: [PATCH 3/7] Add document improvment footer to docs/api --- docs/about.mdx | 2 +- docs/api.mdx | 5 +++++ docs/intro.mdx | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/about.mdx b/docs/about.mdx index fcc1250..7d6cb63 100644 --- a/docs/about.mdx +++ b/docs/about.mdx @@ -66,7 +66,7 @@ The current supported list of services is: -### Improve this documentation +### Improve this document Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. - [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page - [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/api.mdx b/docs/api.mdx index b0cc253..d6eda2d 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -107,3 +107,8 @@ The current supported list of services is: + +### Improve this document +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/intro.mdx b/docs/intro.mdx index 94875e1..4f0d3ca 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -6,5 +6,5 @@ sidebar_position: 1 Use the examples reference documentation to learn how to use Watermelon's suite of products. -This documentation is open source. To contribute, please check out the [GitHub repo](https://github.com/watermelontools/docs). +This documentation is open source. To contribute, please check out the [GitHub repo](https://github.com/watermelon-docs). From e1c9f9786051dc5c49a1f0269f2f505fc9318399 Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 16:21:48 -0500 Subject: [PATCH 4/7] Add getting started with GitHub section --- docs/Security.mdx | 8 ++++++++ docs/api.mdx | 2 +- docs/gettingStartedWithGitHub.mdx | 19 +++++++++++++++++++ docs/gettingStartedWithIntelliJ.mdx | 8 ++++++++ docs/gettingStartedWithVSCode.mdx | 8 ++++++++ 5 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 docs/Security.mdx create mode 100644 docs/gettingStartedWithGitHub.mdx create mode 100644 docs/gettingStartedWithIntelliJ.mdx create mode 100644 docs/gettingStartedWithVSCode.mdx diff --git a/docs/Security.mdx b/docs/Security.mdx new file mode 100644 index 0000000..dfbcfeb --- /dev/null +++ b/docs/Security.mdx @@ -0,0 +1,8 @@ +--- +sidebar_position: 6 +--- + +### Improve this document +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/api.mdx b/docs/api.mdx index d6eda2d..8e78145 100644 --- a/docs/api.mdx +++ b/docs/api.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 7 --- import GitHubLogo from "../static/logos/github.svg"; diff --git a/docs/gettingStartedWithGitHub.mdx b/docs/gettingStartedWithGitHub.mdx new file mode 100644 index 0000000..6dac17f --- /dev/null +++ b/docs/gettingStartedWithGitHub.mdx @@ -0,0 +1,19 @@ +--- +sidebar_position: 3 +--- + +# Getting started with Watermelon's GitHub application + +## Introduction +To start using Watermelon's GitHub application, you need to follow these steps: +- Go to the [Watermelon GitHub marketplace listing](https://github.com/marketplace/watermelon-context) and click "Install it for free" +- Go to the [Watermelon dashboard](https://app.watermelontools.com/) to authorize the app on your GitHub organization or user account +- Once GitHub is authorize, Watermelon will start indexing information on your organization's Pull Requests. Additionally you can go to the dashboard to authorize other services (such as Slack, Notion, or Jira) to contextualize your Pull Requests. + +## Settings +Watermelon shows the 3 most relevant search results for each service on each Pull Request. If you wish to customize the number of search results each service shows, go to the [settings menu](https://app.watermelontools.com/settings) on the dashboard. + +### Improve this document +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/gettingStartedWithIntelliJ.mdx b/docs/gettingStartedWithIntelliJ.mdx new file mode 100644 index 0000000..1119b88 --- /dev/null +++ b/docs/gettingStartedWithIntelliJ.mdx @@ -0,0 +1,8 @@ +--- +sidebar_position: 5 +--- + +### Improve this document +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/gettingStartedWithVSCode.mdx b/docs/gettingStartedWithVSCode.mdx new file mode 100644 index 0000000..92e8d1a --- /dev/null +++ b/docs/gettingStartedWithVSCode.mdx @@ -0,0 +1,8 @@ +--- +sidebar_position: 4 +--- + +### Improve this document +Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. +- [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file From 02ba23500292832eb6167c2568f783351dd821d1 Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 16:38:45 -0500 Subject: [PATCH 5/7] Add IDE pages --- docs/gettingStartedWithIntelliJ.mdx | 7 +++++++ docs/gettingStartedWithVSCode.mdx | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/docs/gettingStartedWithIntelliJ.mdx b/docs/gettingStartedWithIntelliJ.mdx index 1119b88..3f9b704 100644 --- a/docs/gettingStartedWithIntelliJ.mdx +++ b/docs/gettingStartedWithIntelliJ.mdx @@ -2,6 +2,13 @@ sidebar_position: 5 --- +# Getting started with Watermelon's IntelliJ Plugin + +## Introduction +To get started with Watermelon's IntelliJ plugin, you can install it directly from the [JetBrains marketplace](https://plugins.jetbrains.com/plugin/22251-watermelon-intellij-template). With this quick start setup, Watermelon will index info from your local git system. + +Optionally, you can go to the Watermelon dashboard to authorize and let your IDE index information from various information sources such as Slack, Notion and Linear. + ### Improve this document Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. - [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page diff --git a/docs/gettingStartedWithVSCode.mdx b/docs/gettingStartedWithVSCode.mdx index 92e8d1a..f168a6d 100644 --- a/docs/gettingStartedWithVSCode.mdx +++ b/docs/gettingStartedWithVSCode.mdx @@ -2,6 +2,13 @@ sidebar_position: 4 --- +# Getting started with Watermelon's VS Code extension + +## Introduction +To get started with Watermelon's VS Code extension, you can install it directly from the [VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=WatermelonTools.watermelon-tools). With this quick start setup, Watermelon will index info from your local git system. + +Optionally, you can go to the Watermelon dashboard to authorize and let your IDE index information from various information sources such as Slack, Notion and Linear. + ### Improve this document Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. - [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page From 31a918ad339b9a6375b7c6bdea73d6fd97f8c5c6 Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 17:30:15 -0500 Subject: [PATCH 6/7] Add security page --- docs/Security.mdx | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/Security.mdx b/docs/Security.mdx index dfbcfeb..8a78ab3 100644 --- a/docs/Security.mdx +++ b/docs/Security.mdx @@ -2,6 +2,29 @@ sidebar_position: 6 --- +# How Watermelon handles Security + +## Overview +As part of our commitment to transparency and building in public, all of our products are open-source. Being open-source has a wide range of benefits for our users and one of them is that it forces us to build software that's safe. To keep track of this for the general audience, in the README of each one of our repositories, you can find the OSSF scorecard badge that provides a security health metric for the codebase. + +## Encryption +Watermelon use HTTPS for all networking in our products. Your data never travels through our API, or the APIs of the services that we integrate, without being encrypted. + +We use [Vercel Secrets](https://vercel.com/docs/cli/secrets) to store and automatically encrypt all environment variables. + +## Authentication +We use [NextAuth](https://next-auth.js.org/) for authentication to our platform. This open-source library is convenient because it makes use of signed and pre-fixed cookies, without depending on client-side JavaScript. + +To authenticate to different service providers, we store your oAuth token for each service on our Azure DB. + +## Permissions +When you setup Watermelon you authorize your version control system (GitHub, GitLab or Bitbucket) to read your private repositories. The oAuth scopes of these platforms use an "all or nothing" permission model. It's not possible to only select some repositories on your organization. We recognize the desire for more refined and granular scopes in version control systems and are continuously working towards improvements. In the spirit of full transparency, all of our codebases are open-source, ensuring Watermelon's dedication to safeguarding and respecting user code and data. + +## We don't store your code +One of the main reasons we decided to open-source our product is to be able to show, the easiest way possible to our users, that we don't store their code. + +The metadata from your codebase that we do read and send to our APIs to make our passive doucmentation search engine work, are commit messages, commit hashes, and Pull Request metadata. + ### Improve this document Our documentation, as well as our products and our company handbook, are open-source and [available on GitHub](https://github.com/watermelontools/docs). We welcome your contributions. - [Open an issue](https://github.com/watermelontools/docs/issues/new) to report a problem on this page From 64a4f8ede519e04ee6fc00d56e5d6c417e37d122 Mon Sep 17 00:00:00 2001 From: baristaGeek Date: Tue, 22 Aug 2023 17:34:52 -0500 Subject: [PATCH 7/7] Make small wording change on intro --- docs/intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro.mdx b/docs/intro.mdx index 4f0d3ca..81a853d 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -4,7 +4,7 @@ sidebar_position: 1 # Welcome to Watermelon Documentation -Use the examples reference documentation to learn how to use Watermelon's suite of products. +Use the reference documentation to learn how to use Watermelon's suite of products. This documentation is open source. To contribute, please check out the [GitHub repo](https://github.com/watermelon-docs).