# Contribution Guide

> [[todo]] [[good-first-task]] This contribution guide itself could be improved 😅

Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback. Here are some general tips on how to get started on contributing to Foam:

- Use Foam for yourself, figure out what could be improved.
- Check out [[roadmap]] to see what's already in the plans. I have thoughts about how to implement some of these, but open to ideas and code contributions!
- Read about our [[principles]] to understand Foam's philosophy and direction
- Read and act in accordance with our [[code-of-conduct]].
- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
- Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/)
  - [/docs](https://github.com/foambubble/foam/docs): documentation and [[recipes]]
  - [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode): the core VSCode plugin
  - [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core): powers the core functionality in Foam across all platforms
- Exceptions to the monorepo are:
  - The starter template at [foambubble/foam-template](https://github.com/foambubble/)
  - All other [[recommended-extensions]] live in their respective GitHub repos.

## Contributing to the VS Code Extension

If you're interested in contributing to the VS Code extension (aka `foam-vscode`), this 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 workspace foam-core build`

4. 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.
5. 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). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
6. 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]]

[//begin]: # "Autogenerated link references for markdown compatibility"
[todo]: todo "Todo"
[good-first-task]: good-first-task "Good First Task"
[roadmap]: roadmap "Roadmap"
[principles]: principles "Principles"
[code-of-conduct]: code-of-conduct "Code of Conduct"
[recipes]: recipes "Recipes"
[recommended-extensions]: recommended-extensions "Recommended Extensions"
[tutorial-adding-a-new-command-to-the-vs-code-extension]: tutorial-adding-a-new-command-to-the-vs-code-extension "Tutorial: Adding a New Command to the VS Code Extension"
[//end]: # "Autogenerated link references"
