In this document, you'll learn how to run Briefer in development mode and how to contribute to the project.

• Running Briefer in dev mode
• Questions, bugs, and feature requests
• Submitting pull requests
• Troubleshooting

This guide serves to set clear expectations for everyone involved with the project so that we can improve it together while also creating a welcoming space for everyone to participate. Following these guidelines will help ensure a positive experience for contributors and maintainers.

You need to be able to run Briefer in development mode to contribute to the project and test changes.

Below are the steps to run Briefer in development mode.

Briefer runs on Docker, so you'll need to have it installed on your machine. If you don't have it yet, you can download it here.

Briefer also uses Docker Compose, so make sure you have it too. In more recent versions of Docker, Compose is already included.

Besides that, you'll need to have Node.js (we currently use Node v18) and Yarn installed on your machine. You can download them here and here, respectively.

After installing the dependencies, you'll have to run the database, Jupyter instance, and demo database to which Briefer will connect.

To do that, run the following command in the root folder of the project:

./start-dev.sh

This command will create the necessary .env files and run the docker-compose.dev.yaml file.

Finally, you'll need to install Briefer's dependencies and start the project.

To do that, run the following commands in the root folder of the project:

yarn install

After installing the dependencies, you can start Briefer by running:

yarn dev

Briefer's AI service is a separate service that generates code for the AI features, like "Edit with AI" and "Fix with AI". You don't necessarily need to run it, unless you're working on these features or want to use them.

To run it, you'll need to have Python 3.9 installed on your machine.

After installing Python, we recommend creating a virtual environment to install the dependencies of the AI service.

cd ai
virtualenv venv

After creating the virtual environment, you can activate it by running:

source venv/bin/activate

Then, you can install the dependencies by running:

# you may need to `brew install mysql pkg-config` before
pip install -r requirements.txt

Finally, you can start the AI service by running:

python3 main.py

Here are a few things to try if you have trouble running Briefer in development mode.

1. Ensure you're running the latest version of Docker and Docker Compose.
2. Double-check that you have Node.js and Yarn installed, and make sure that you're using Node v18.
3. Reinstall the dependencies by removing the node_modules folder and running yarn install again. Please ensure that you're running Node v18 during the installation.
4. If you're having trouble running the AI service, ensure that you have Python 3.9 installed and that you've created a virtual environment for it. Also, make sure that you've installed the dependencies by running pip install -r requirements.txt.
5. If you can't find the necessary .env files within each app's folder, try running ./start-dev.sh again.
6. In case the applications complain about missing environment variables, you can always delete the .env files and run ./start-dev.sh again to recreate them.

If you still can't run Briefer properly after following these instructions, please open an issue here.

At Briefer, we'd rather have you ask questions than wander around in the dark or waste time on something that could be easily solved.

Do not be afraid to ask questions. We are here to help you!

Here's when you should, ideally, open an issue:

• You've found a bug in Briefer.
• You have a feature request.
• You can't run Briefer in development mode.
• You're having trouble deploying Briefer.

In all other cases, we'd recommend that you get in touch using our Slack community. If you're not part of it yet, you can join by clicking here.

In any case, either by opening an issue or asking a question in our Slack community, please provide as much information as you can. This will help us help you.

Finally, if you're not sure whether you should open an issue or ask a question on Slack, just do what feels right to you - it's all good. ✌️

If you've found a security issue in Briefer, please don't open an issue. Instead, send an email to founders@briefer.cloud or open the Vunerability Report using the Security tab in this repository. Additionally read our Security Policy

Anyone can submit a pull request to Briefer. We welcome contributions from everyone, regardless of their experience level.

If you're new to open-source or to Briefer, you can start by looking at the issues labeled as good first issue. These issues are usually smaller and easier to tackle, making them a great starting point for new contributors.

When opening a pull request, please make sure to fill the template with as much information as you can. This will help us understand your contribution and review it more effectively.

After submitting a pull request, please make sure to sign our CLA (Contributor License Agreement) by following the instructions that our bot will provide you. This is a necessary step for us to accept your contribution.

Below are some common errors and their possible fixes. Please feel free to open an issue if none of these suggested fixes work.

RuntimeError: Permissions assignment failed for secure file: '/home/jupyteruser/.local/share/jupyter/runtime/jpserver-8.json'. Got '0o677' instead of '0o0600'.

mkdir -p ./jupyterfiles
sudo chown -R $(whoami):$(whoami) ./jupyterfiles
mkdir -p ./jupyterfiles/.local/share/jupyter