Skip to content

Add CONTRIBUTING.md in vscode extension and top-level install commands #753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 8, 2025

Conversation

lionel-
Copy link
Collaborator

@lionel- lionel- commented Jul 4, 2025

Taking example on Biome, we've started using the just command runner in Ark and Air. I've started one in the vscode extesion to easily install it in Code and Positron and build it in dev/watch mode.

The new contributing file describes our dev workflows.

@lionel- lionel- requested a review from juliasilge July 4, 2025 07:01
@cderv
Copy link
Contributor

cderv commented Jul 4, 2025

we've started using the just command runner

Cool! I like this tool too!

Thanks for your contribution @lionel- !

Copy link
Collaborator

@juliasilge juliasilge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the other runner type support in this repo is at the root. Can we set up the just file so that it also runs from the root, for consistency?

What do you think about putting CONTRIBUTING.md in its regular location in .github or also at the root? I wouldn't know to look for it where it currently is.

@lionel-
Copy link
Collaborator Author

lionel- commented Jul 5, 2025

hmm I think the current location has advantages. The justfile in this location can contain easy shortcuts that are only relevant for vscode dev. If you put it in the root then all vscode-only commands would need to be namespaced, making them less convenient. And there will be a barrier to adding very specialised commands in there as the file is shared with many projects.

Similarly the contributing file in the vscode folder is very focused. At the root it could potentially scale to a very large document that is harder to read and less likely to be updated with finer details.

Having a contributing file at the root is a good idea but it could be more like an orientation file that links to the subproject dev docs. Likewise, a justfile at the root would contain very general commands pertaining to the monorepo as a whole.

@juliasilge
Copy link
Collaborator

The justfile in this location can contain easy shortcuts that are only relevant for vscode dev

A chunk of the build scripts that we already have are only relevant for the VS code extension, and I am worried about having things that are so similar in multiple places, from a dev experience perspective. Folks won't have a way to know they are even there; please move them to be together with the other build scripts.

If you want to keep this CONTRIBUTING.md where it is, can you add a link in the README under the current instructions to do yarn dev-vscode? Perhaps add the just commands there and then also link, calling out that there is info about debugging the LSP?

@lionel- lionel- force-pushed the task/vscode-contributing branch from 8a31dce to f990edc Compare July 7, 2025 08:13
@lionel-
Copy link
Collaborator Author

lionel- commented Jul 7, 2025

On the other hand, having a justfile at the top-level is a different matter since, as you mention, we already have a top-level workflow. Are we ready to add a justfile at top-level in addition to our existing yarn commands? To avoid any confusion, I've removed the justfile and added the relevant scripts as top-level yarn commands.

The top-level readme now links into our project's contributing file for easier access.

@cscheid
Copy link
Contributor

cscheid commented Jul 7, 2025

I just want to register here a preference here for trying hard to reduce tool proliferation. This kind of proliferation adds drag to everyone and is hard to revert.

I understand that quarto-dev/quarto is now a place where folks with a large number of backgrounds come to contribute and that makes what I'm asking a tricky proposition. But we really ought to spend energy being intentional about the long-term impact of this kind of thing.

I don't feel sufficiently knowledgeable about this entire repo to make this a strong preference. But I want to register here that this sets off some alarms in my head.

@lionel-
Copy link
Collaborator Author

lionel- commented Jul 7, 2025

I've now removed the justfile but I just wanted to clarify why we use it in our other projects:

  • It's a way to document various useful CI gestures as well as provide shortcuts for them.
  • It's a way to abstract away the web-devy workflows which we are not very familiar with still.
  • It allows indirections on some aspects of the workflow. For instance in ark just test maps to cargo nextest instead of cargo test.

While it is an additional tool in the stack, I the benefits of this tool actually reduce the burden of tool multiplicity.

Copy link
Collaborator

@juliasilge juliasilge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @lionel- ❤️

This repo is definitely a tricky one from a dev experience perspective since multiple teams work on it, but only part-time.

@lionel- lionel- changed the title Add justfile and CONTRIBUTING.md in vscode extension Add CONTRIBUTING.md in vscode extension and top-level install commands Jul 8, 2025
@lionel- lionel- merged commit 8260949 into main Jul 8, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants