mirror of
https://github.com/foambubble/foam.git
synced 2026-04-24 03:01:01 -04:00
75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
---
|
|
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` 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"
|