VBLang Repo lacks clarity

[KathleenDollard]

The vblang repo lacks clarity, particularly in terms of what can be expected to be worked on. @bandleader described it as "a mess" in .

From @bandleader's comments:

• there are tons of issues with no response from Microsoft at all
• many issues are describing scenarios that should be combined into one feature (must create issue for the full feature, describe which issues this supersedes. take in the most accepted syntax/ideas of the other issues, then CLOSE them)
• some issues are not clearly defined, written in hard-to-understand English, or propose changes that cause grammar ambiguity (not everyone > understands compilers) or solve too narrow a scope of scenarios, and the issue needs to be clarified, corrected, and sometimes integrated > into a new issue.

Also:

• there are several issues that are different proposed solutions for the same problem.

I absolutely want to provide clarity to this repo and avoid anyone being forced to reopen existing issues.

Drawing ideas from other repos helps consistency, but this repo is unique in many ways. I think we will be best served if this repo serves as one mechanism for strengthening community. I assume this repo has been frustrating at times, and my goal is to reduce that.

This discussion is only for the VBLang repo. Other repos, like the Roslyn repo is an intense working repo that requires different and generally stricter management.

[KathleenDollard]

The VBLang team has committed to reviewing all open issues. This will take a while. I was going to work in reverse chronological order, but I think reverse chronological on last comment is best. So if there is something you want reviewed early, please make a comment - ideally indicating why you think it should be reviewed.

Issues should not state only a problem and not a solution. I believe it is absolutely critical to the design process to consider all possible implementations of a solution to a problem. You could both open the issue and include your solution as a comment, but all solutions and enhanced understanding of the issue would be comments.

I propose that we be rather strict on this, to the point of closing and either recreating or asking the author to recreate issues that do not follow this pattern. In the current state of the repo, this would allow a single place to clarify why Flags enums are difficult in VB, and see @AdamSpeight2008, @AnthonyDGreen and my ideas side by side - along with your ideas without having to get to the point of a formal proposal. This will also make it much easier to interact with the languages team who can more deeply gauge technical aspects of the solution.

As the team reviews issues, they will combine them and link as required to group. All issues that have been reviewed will be tagged. I don't intend this to always shut down that conversation - tell us if you think we are wrong. But I also don't for us to waste time.

I feel quite strongly that someone should be able to walk up to this repo and say "Wow, VB is considering xxx" and "Oh! VB folks are talking about yyy." I also feel quite strongly that problems be identified and then different solutions have a level playing field. I suggest we do that by having proposals will be considered only after an issue has been discussed. This avoids confusion about what proposals are under serious consideration and helps people that want to make a commitment only to respond to proposals. If you want more detail than you think make sense in a comment, that's great and you can use a gist or other place.

I have mixed feelings on prototypes. On the one hand, it's a way for you to determine if your idea makes sense and is doable. On the other hand, not everyone has the same capacity to build them. So I suggest that we allow prototypes (I think @AnthonyDGreen has some in mind, and I would not want to discourage him), but explicitly not allow them to tilt the playing field toward the prototyped version - beyond the obvious that it represents research completed. If your a VB leader, and I think everyone here is, then your ideas are very important and your contributions to community. Those are the things I want to encourage most.

@AdamSpeight2008 brought up adding a wiki, and I'm going to split it into VBLang/language transparency issues and community support.

A wiki / use of the projects feature on this repo would be a nice addition, may also attract contributor to pick off outstanding tasks.

Proposals
Need specifications written,
Proof-Of-Concept prototypes.
References to forks, so others could contribute or help develop it.
...

I feel that most of this is better solved with repo organization, and notes in the readme, so people new to the repo don't need to understand that this stuff is in the wiki. Plus some of this ("Needs spec..") can easily get out of date. But definitely a possibility.

[AdamSpeight2008]

@KathleenDollard
On Prototypes i think that we should have page dedicated to how to contribute features.

• Fork and branch the VRLang repo ( with the name of there feature / design )
• Include a Proposal specification,
  • This can be updated and pushed to VBLang as progress indication.
  • Link to the Issue your provide at prototype for.
  • How it provides a solution.
  • Link to your branch of the Roslyn include declaration of the state of implementation.
    • DON'T PUSH TO THE ROSLYN REPO
      • Without alerting them first.
    • Parsing, Binding, Lowering, Emitter. etc
    • Eg It mostly parse. It parses but don't compile. etc.
    • Any updates to the Tooling;- Colorisation, Formatting Code Fix etc
  • Issues with a specific prototype, should be raised
    • on then corrisponding repo
    • on the Pull Request.

[AdamSpeight2008]

@KathleenDollard
We should also have page that expresses the Language Style the developer can follow when implementing features. It may carry more weight if this came for the VB.net community, that the Roslyn may accept it.

[KathleenDollard]

@AdamSpeight2008

I'm assuming you just left out the first step - discuss as an issue that states the problem initially without a solution and allow all possible solutions to be discussed and noodled on. :)

We want to drop the "without alerting them first." That process will be that we'll take the issue/proposal that will move forward, and at that point we'll assign a team engineer to shepherd through our non-trivial internal processes.

So, basically, I agree we need to fine tune a set of instructions about how to contribute and just need to tune the instructions and the text. I think it also might want to include a mechanism (not sure what it is) to get help from this community, since the engineers really don't have cycles for that.

[KathleenDollard]

@AdamSpeight2008 On Language Style, doesn't this already exist in the Roslyn repo? I don't know why VB would be different than that.

[gafter]

I think it would be a good idea to keep the language repo and the roslyn repo separate from each other. The vblang repo is where we request language features, noodle on different ways the feature might present itself in the language, and possibly get buy-in from the language design group that a given design is OK to proceed, and possibly when.

The Roslyn repo, on the other hand, is where compiler work goes. It is where we talk about implementation ideas, coding guidelines, parsing, scanning, lowering, etc. We talk about feature design there, but not language feature design. For example, we might talk about changes to the compiler command-line flags, generating reference assemblies, warning waves, and other compiler-specific features. Once a language design has been tentatively approved (discussed here), a next step can be a prototype of the design (in the Roslyn repo).

We don't need to document anything about a particular compiler in this repo. We talk about the language design here. In the Roslyn repo we discuss implementation (one particular compiler).

[bandleader]

The VBLang team has committed to reviewing all open issues. This will take a while. I was going to work in reverse chronological order, but I think reverse chronological on last comment is best.

@KathleenDollard @gafter Here is quick bookmarkarble URL to the list of open issues, sorted by most recently updated:

• https://github.com/dotnet/vblang/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc

[KathleenDollard]

@gafter I agree. If I said anything that was not in agreement with this explanation of the repo differences it was not intentional. I appreciate your ongoing help in keeping things organized, and if I said something confusing, I'd love to clarify.

[gafter]

@KathleenDollard I think we are on the same page.

[AdamSpeight2008]

@KathleenDollard @gafter I'm on a different page / book.
VBLang Issues should be considered as scratch pad for Ideas where they are discussed.
The Roslyn LDM should only be discussing the Pull Requests with this repo not issues., as these are considered by the VBLang community as viable designs for incorporating into the Visual Basic language.
Roslyn repository is where additions to the feature official language specification is written, updates and correction can be submitted here as PRs for LDM to review.

We as community should be welcoming community members that want to the freedom to experiment and explore the VIsual Basic language. To see where the potentially the language could go, the VB LDM then decides to destination, not the map we are using.

[AdamSpeight2008]

In the current state of the repo, this would allow a single place to clarify why Flags enums are difficult in VB, and see @AdamSpeight2008, @AnthonyDGreen and my ideas side by side - along with your ideas without having to get to the point of a formal proposal.

@KathleenDollard
Interesting use of language within your reply., which suggests (to me) a division of you (the Roslyn side of VBLang repo and the VB Community see this repo.

This will also make it much easier to interact with the languages team who can more deeply gauge technical aspects of the solution.

See my previous reply for a how this could work.

[AdamSpeight2008]

@AdamSpeight2008
I'm assuming you just left out the first step - discuss as an issue that states the problem initially without a solution and allow all possible solutions to be discussed and noodled on. :)

I left it out because I was discussing Prototypes, the problem would have be already touch on.

[AdamSpeight2008]

@KathleenDollard If there ain't any notes from LDM swhere VB.net has been discussed on the Repo, effectively for the rest of the community that meeting never took place. Any decisions or feedback never happened. Hence why they feel out of the loop and as second class citizens.

[bandleader]

@AdamSpeight2008 The Roslyn LDM should only be discussing the Pull Requests with this repo not issues.

Why? This repo is for language design -- we suggest language features to add to VB, and not necessarily their final implementation. (Most of us aren't very familiar with the Roslyn codebase, and won't be contributing prototypes, but have valuable input on features, which we contribute in the issues.)
The actual changes to Roslyn (including spec changes) are done in the Roslyn repo, either by the good folks at Roslyn team that MS pays to do so, or by generous community members like yourself. In the past @AnthonyDGreen would present the issues at the LDMs and that's how they would move forward.