bra1nDump commented 11 months ago

Ideally a new contributor would clone the project, open root in vscode, hit F5 and it will start both server / extension and they can immediately set breakpoints in both server / extension and start exploring how to code works.

Current issues

There is no single place in the documentation that describes how to run both VSCode extension + server with debugging enabled
The projects have to be debugged from different VSCode windows
[Needs a separate issue] Documentation on getting it to work is scattered (especially for the VSCode extension portion across extension/src/README.md and extension/DEV_README.md extension/README.md)

Suggestions

I am experimenting locally with the suggestions below locally and will create a PR once I make progress. The order is my suggested order of implementation.

1. Improve debugging setup for VSCode extension

Create its own launch.json entry to debug extension so you don't have to be focused on a .ts file or be in the extension root
Get watch build task to work so on file save the new code gets picked up by the extension host (where the extension being debugged is running)
- Requires a reload of the extension host

2. Improve overall experience for workspace (aka Server + Extension development)

The goal is to allow seamless debugging of all components

Option 1 - multi root workspace

[Developer experience] Open root or sub projects to work on either server or extension, they open Run and debug sidebar and run a different configuration depending what they want to work on, the options available will depend on if the top level workspace is opened or an individual project.
Create nested launch.json configurations in each subproject and reference them in top level
[Con] Not a popular feature - 7 projects on github use this https://github.com/search?q=.+path%3A*..code-workspace&type=Code&ref=advsearch&l=&l=
[Pro] Keeps status quo by allowing to open server only or extension only to avoid distractions by opening the root folder

[My vote] Option 2 - move all launch configurations to root

[Developer experience] Similar to last option, but always open root of the project to work on either server or extension
Have 3 launch configurations in the top level - server only, extension only and a both (using launch.json compounds)
[Pro] More common practice it seems

3. Improve dependencies setup

The goal is to have a single vscode task / bash script we can run to install all components needed for development. Motivation for lower priority is this is a one time setup fee where as the above improvements will be useful every time the project is worked on.

Installing poetry
Creating the virtual environment
Setting up python interpreter
npm install

References

A project I am familiar with that has very good devx and I am using it as a reference for some of the suggestions: https://github.com/cursorless-dev/cursorless
https://code.visualstudio.com/docs/editor/multi-root-workspaces
https://code.visualstudio.com/Docs/editor/debugging#_compound-launch-configurations

sestinj commented 11 months ago

@bra1nDump Love this! I'll give a deeper look tomorrow, including improving the documentation in CONTRIBUTING.md, but I agree that option 2 is the better choice. Also take a look at npm run package in extension/package.json, which does a lot of the steps required for setup, and extension/scripts/install_from_source.py, which is a more complete option, but also builds and installs a .vsix file. Something between these two is what you describe in step 3, but you could borrow heavily from them.