---
tags: todo, good-first-task
---
# Contribution Guide
Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback.
This guide aims to help guide new and seasoned contributors getting around the Foam codebase.

## Getting Up To Speed
Before you start contributing we recommend that you read the following links:

- [[principles]] - This document describes the guiding principles behind Foam.
- [[code-of-conduct]] - Rules we hope every contributor aims to follow, allowing everyone to participate in our community!

## Diving In
We understand that diving in an unfamiliar codebase may seem scary,
to make it easier for new contributors we provide some resources:
- [[architecture]] - This document describes the architecture of Foam and how the repository is structured.

You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
Finally, the easiest way to help, is to use it and provide feedback by [submitting issues](https://github.com/foambubble/foam/issues/new/choose) or participating in the [Foam Community Discord](https://foambubble.github.io/join-discord/g)!

## Contributing

If you're interested in contributing, this short guide will help you get things set up locally.

1. Clone the repo locally:

   `git clone https://github.com/foambubble/foam.git`

2. Install the necessary dependencies by running this command from the root:

   `yarn install`

3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). `foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:

   `yarn build`

You should now be ready to start working!

### Testing

Code needs to come with tests.
We use the following convention in Foam:
- *.test.ts are unit tests
- *.spec.ts are integration tests

Also, note that tests in `foam-core` and `foam-cli` live in the `test` directory.
Tests in `foam-vscode` live alongside the code in `src`.

### The VS Code Extension

This guide assumes you read the previous instructions and you're set up to work on Foam.

1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. From the root, or the `foam-vscode` workspace, press f5.

2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.

3. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!

For more resources related to the VS Code Extension, check out the links below:

- [[tutorial-adding-a-new-command-to-the-vs-code-extension]]

---

Feel free to modify and submit a PR if this guide is out-of-date or contains errors!

---

[//begin]: # "Autogenerated link references for markdown compatibility"
[principles]: principles.md "Principles"
[code-of-conduct]: code-of-conduct.md "Code of Conduct"
[architecture]: dev/architecture.md "Architecture"
[//end]: # "Autogenerated link references"