Contributing

September 6, 2023 · View on GitHub

We discuss both on GitHub Issues and Discord.

Contributing to Watermelon's Passive Documentation Search Engine

Anyone is free to contribute changes to any file in this repository. You don't need to ask for permission or get in line. If you see an issue that's open and it seems interesting to you, feel free to pick it up. Your solution may be better. Open-source is beautiful.

Exception: If your contribution makes paid Watermelon feature available for free, we are unlikely to accept it. Consult us beforehand for a definitive answer.

Running the Passive Documentation Search Engine Locally

To start developing, clone and:

yarn
yarn dev

Or with npm

npm i
npm run dev

(Check your node version, we recommend 18)

We use a recent version of Next. You may refer to the documentation.

This repo is automatically deployed on vercel to app.watermelontools.com on merges to main.

All the backend lives as serverless functions under api, with the route being the filename.

We now use the new app router for all features.

As we use OAuth2.0, local development cannot be done on new integrations.

All environment vars are on vercel, the committer is responsible for correct deployments.

Getting started

We develop with a model that forces a lot of things to be done by the developer. As this is a monorepo you have to be very careful.

PLEASE READ THE DOCS FOLDER

PLEASE READ THE CODE OF CONDUCT

APIs

We have a utils folder that includes all the business logic. We have an api folder that handles web communication as dictated by NextJS. In the types folder we hold our typescript types, that should (roughly) match what our database has.

The developer has to match the utils folder structure to the api route schema. This makes it easier to maintain.

As an example, we have utils/user/getProfile.ts that is imported in app/api/user/getProfile.ts and returns a types/UserProfile.ts. In the database, you will find a user table with all the data on the type.

We do all of this as a security measure. We don't want data exposed and we consider our backend safe.

New integrations

To integrate a new service, several steps are to be taken, but it's pretty much copying code.

First, we use oauth so you need to ensure that the service supports it.

Remember that there are several procedures in our db to replicate.

The steps to do so are:

Publicly announce the new integration

serviceName refers to the shortname, like github or gitlab, lowercase ServiceReadableName refers to the name of the service and it's use in the UI, like GitHubPRs or LinearTasks
Set the necesary vercel env vars

usually SERVICE_CLIENT_SECRET and SERVICE_CLIENT_ID
Create the table in our DB

This is sketch of a possible new table

Add any other required columns as needed

  CREATE TABLE serviceName (
    id INT PRIMARY KEY,
    name VARCHAR(255),
    email VARCHAR(255),
    updated_at DATETIME DEFAULT GETDATE() NOT NULL,
    created_at DATETIME DEFAULT GETDATE() NOT NULL,
    access_token VARCHAR(255),
    refresh_token VARCHAR(255),
    avatar_url VARCHAR(255),
    workspace VARCHAR(255),
    workspace_image VARCHAR(255),
    watermelon_user VARCHAR(255),
    deleted BIT DEFAULT 0 NULL,
    deleted_at DATETIME DEFAULT GETDATE() NULL,
    FOREIGN KEY (watermelon_user) REFERENCES watermelon.dbo.users(id)
    );

Edit the userSettings table

ALTER TABLE userSettings ADD ServiceReadableName INT DEFAULT 3;`

UPDATE userSettings SET ServiceReadableName = 3 WHERE ServiceReadableName IS NULL;

Create the necessary procedures

Setting the information for the user using create_serviceName

CREATE PROCEDURE dbo.create_serviceName
    @access_token varchar(255),
    @id varchar(255),
    @name varchar(255),
    @displayName varchar(255),
    @email varchar(255),
    @avatarUrl varchar(255),
    @team_id varchar(255),
    @team_name varchar(255),
    @watermelon_user varchar(255)
AS
DECLARE @insertTable TABLE (
    access_token varchar(255),
    id varchar(255),
    name varchar(255),
    displayName varchar(255),
    email varchar(255),
    avatarUrl varchar(255),
    team_id varchar(255),
    team_name varchar(255),
    watermelon_user varchar(255)
)

DECLARE @wmid VARCHAR(255) = (
SELECT
  id
FROM
  dbo.users
WHERE
  email = @watermelon_user
)

INSERT
  INTO
  dbo.serviceName
    (
    access_token,
  id,
  name,
  displayName,
  email,
  avatarUrl,
  team_id,
  team_name,
  watermelon_user
    )
OUTPUT
inserted.access_token,
  inserted.id,
  inserted.name,
  inserted.displayName,
  inserted.email,
  inserted.avatarUrl,
  inserted.team_id,
  inserted.team_name,
  inserted.watermelon_user
    INTO
  @insertTable
VALUES
    (
    @access_token,
    @id,
    @name,
    @displayName,
    @email,
    @avatarUrl,
    @team_id,
    @team_name,
    @wmid
    )

SELECT
  *
FROM
  @insertTable
FOR JSON PATH,
WITHOUT_ARRAY_WRAPPER

Fetching the settings is unchanged as we use the same procedure for all services
Edit the settings getter
Fetching the tokens
- Edit the procedure get_all_user_tokens to match the service
- Edit the procedure get_all_tokens_from_gh_username to match the service
Create a ServiceLoginLink.ts component in the components folder
Add the service to the loginArray.tsx file
Add the service to the loginGrid.tsx file in the correct section
Add the service to form.tsx under settings
Run the newIntegration.sh script which will:
- Create the service folder under (loggedIn)
- Copy the loading.tsx from any other service
- Create the function under /utils/db/service/saveUser that you need to complete
- Populate the page.tsx file to be finished the correct service parameters
- Create an empty getter in /utils/actions
Now you need to edit the page.tsx file to match the service
Get the data in the getService.tsx file under actions
Add to the action log
Pass the data to the AI in utils/actions/getOpenAISummary.ts file
Return the data as Markdown in api/actions/github/route.tsx
Return one result in api/hover/route.tsx
Return the settings decided results in api/extension/route.tsx

Octokit (SDK for GitHub)