Skip to content

Comments

Add CHANGELOG and new README#426

Merged
doriable merged 9 commits intomainfrom
add-changelog-new-readme
Aug 18, 2025
Merged

Add CHANGELOG and new README#426
doriable merged 9 commits intomainfrom
add-changelog-new-readme

Conversation

@doriable
Copy link
Member

@doriable doriable commented Aug 6, 2025

This PR separates the CHANGELOG from the README
and introduces some new content for both in preparation
to launch a new version of VS Code Buf with the LSP.

@doriable doriable marked this pull request as ready for review August 7, 2025 15:32
README.md Outdated
# Buf for Visual Studio Code

The [VS Code Buf extension](https://marketplace.visualstudio.com/items?itemName=bufbuild.vscode-buf) provides rich support for [Protocol Buffers](https://protobuf.dev/) using the [Buf](https://buf.build/) development environment.
The [VS Code Buf extension][vs-code-marketplace] provides rich support for [Protocol Buffers][protobuf] using the [Buf][buf] development environment.

Choose a reason for hiding this comment

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

Might suggest being a bit more direct with the problem we're solving. Something like...

The [VS Code Buf extension][vs-code-marketplace] helps you work with [Protocol Buffers][protobuf] files in a much more intuitive way, adding smart syntax highlighting, navigation, formatting, and Buf command support.

Copy link
Member Author

Choose a reason for hiding this comment

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

I took a stab at making this a little bit more concrete, let me know your thoughts on this!

Copy link

@robconery robconery left a comment

Choose a reason for hiding this comment

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

General comment - might be a good idea to add to development.md:

  • install packages with npm I
  • run npm run compile to create the out folder, which the extension needs.
  • Run/debug on Mac, for some reason, is borked for me. Not sure why but I can't get the extensions to start properly as they're all disabled. I get a prompt to update the Buf extension and when I do, I lose all .proto functionality.
  • The GIF is super hard to read, which is where this all started as I was going to snap a new one for y'all :) and I couldn't get anything to run.

In addition, I think it would be useful to add a target in your Makefile to compile the ts bits first, as a fresh git clone will likely fail the build (mine did) because out isn't present because we haven't compiled just yet :). Happy to PR this if you like, but didn't want to cross wires, otherwise I took a stab at an update:

.DEFAULT_GOAL := package

.PHONY: check-install compile package
package: compile
	npm run package

.PHONY: install
install:
	npm install

.PHONY: check-install
check-install:
	@if [ ! -d "node_modules" ]; then \
		echo "installing npm packages..."; \
		npm install; \
	fi

.PHONY: compile
compile: check-install
	npm run compile

I'll keep plodding along here and I'll send a note in slack too.


- Visual Studio Code
- A [Buf](https://buf.build/) configuration environment.
![Preview features](./preview.gif)

Choose a reason for hiding this comment

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

Left a general note above, but just to add here - this Gif is really hard to see. I'm happy to redo it for you if I can get up an running over here.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes please, would happily take this offer once we get the development environment stuff sorted out!

@doriable
Copy link
Member Author

Thank you both for the review comments!

@jrinehart-buf - Adjusted the wording according to the feedback, thank you for taking the time to look over it!

@robconery - I appreciate the thoroughness, thank you! Responded directly to some of the comments + some stuff around the extension devx below:

install packages with npm I
run npm run compile to create the out folder, which the extension needs.

I can add a note about npm install, but I am not sure if we should add the follow-up on the out folder.
When using the VS Code debugger with "Run extension", it runs the build with watch, which would refresh the extension when there are source changes. In the case where the development workflow calls npm prepackage, it actually runs the npm prepublish script, which also builds, so that should be taken care of.

I took some time to go through the nitty gritty bits of the extension, including going through and testing VS Code version compatibilities, etc. to make sure we have the right support versions set (e.g. #431).

We can discuss the Makefile changes in #427, but I think that adding the note to ensure that all npm packages are installed should be sufficient. Let me know if this makes sense!

Copy link
Member

@smallsamantha smallsamantha left a comment

Choose a reason for hiding this comment

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

Approving for dev release, we can follow up with additional changes

@doriable doriable merged commit 9e23bce into main Aug 18, 2025
5 checks passed
@doriable doriable deleted the add-changelog-new-readme branch August 18, 2025 13:24
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