diff --git a/docs/Security.mdx b/docs/Security.mdx new file mode 100644 index 0000000..8a78ab3 --- /dev/null +++ b/docs/Security.mdx @@ -0,0 +1,31 @@ +--- +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 +- [Join our Discord community](https://discord.com/invite/H4AE6b9442) to share feedback with us \ No newline at end of file diff --git a/docs/about.mdx b/docs/about.mdx new file mode 100644 index 0000000..7d6cb63 --- /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 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 new file mode 100644 index 0000000..8e78145 --- /dev/null +++ b/docs/api.mdx @@ -0,0 +1,114 @@ +--- +sidebar_position: 7 +--- + +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: + + + +### 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/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..3f9b704 --- /dev/null +++ b/docs/gettingStartedWithIntelliJ.mdx @@ -0,0 +1,15 @@ +--- +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 +- [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..f168a6d --- /dev/null +++ b/docs/gettingStartedWithVSCode.mdx @@ -0,0 +1,15 @@ +--- +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 +- [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 f268222..81a853d 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -2,108 +2,9 @@ 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"; +# Welcome to Watermelon Documentation -# Watermelon API +Use the reference documentation to learn how to use Watermelon's suite of products. -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. +This documentation is open source. To contribute, please check out the [GitHub repo](https://github.com/watermelon-docs). -## 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: - -