Add a design index #190

omajid · 2021-03-19T05:12:05Z

I had trouble trying to navigate designs, so maybe an overview will help others find designs too.

Some designs are clearly marked with a title and PM/Dev assignments. Some subdesigns, unfortunately, are marked the same way. So we have trouble finding main vs sub-designs.

You can see a fully rendered version here.

danmoseley · 2021-03-19T05:45:06Z

@terrajobst

danmoseley · 2021-03-19T05:47:22Z

Thanks for doing this. Any reason you didn't do the table in markdown? Not sure we have much HTML in the repo. Markdown is easier to edit and diff.

mhutch · 2021-03-19T09:27:44Z

This omits a lot of designs - many do not declare a PM or dev owner.

omajid · 2021-03-19T13:14:37Z

Any reason you didn't do the table in markdown?

Uh... I didnt' realize markdown supported tables directly. I am definitely going to fix this.

This omits a lot of designs - many do not declare a PM or dev owner.

Yes, that's true. I used git history to find some owners for some proposals and fix them up. I am going to try and fix up others too. I wanted to get this out for general feedback before I take care of all the details.

omajid · 2021-03-20T22:27:08Z

I don't really know the formal roles of many people at Microsoft. I tried to guess their roles and I probably got some wrong.

From reading the generated table, I think there might be some improvements we want to consider to the design template:

What release the design was/is going to be delivered into
Whether the design still active (was it, perhaps, obsoleted by other designs or considerations?)
Whether the design was fully implemented (or maybe abandoned?)

But we don't have that information in a machine readable way yet.

https://openjdk.java.net/jeps/0 and https://www.python.org/dev/peps/ might also serve as additional sources for inspiration.

INDEX.md

danmoseley · 2021-03-22T05:38:54Z

Re roles: in that table, Claire, Sourabh, Immo, Rich, Kathleen are PM's and the others are Devs.

Personally, I don't think it's necessary to distinguish them. We are quite fluid with who does what. Many designs only have one or the other. But I don't feel strongly either way.

I had trouble trying to navigate designs, so maybe an overview will help others find designs too. Some designs are clearly marked with a title and PM/Dev assignments. Some subdesigns, unfortunately, are marked the same way. So we have trouble finding main vs sub-designs.

omajid · 2021-03-24T00:58:53Z

Personally, I don't think it's necessary to distinguish them. We are quite fluid with who does what. Many designs only have one or the other. But I don't feel strongly either way.

Okay. I kept them in the original design files (since the design template asks for it), but the index now just shows Owners without distinguishing who does what.

terrajobst · 2021-03-24T01:38:36Z

I'm ambivalent on this. On the one hand, I like the single file for Ctrl+F. On the other hand, it seems it's yet another thing that will go out of sync fast.

There are two ways we could address that:

Add CI that validates that the index.md file links your document
Use GitHub actions to automatically add the line to the index.md file upon merge (tricky, need to avoid triggering itself)

danmoseley · 2021-03-24T01:50:36Z

my 2c. it seems easy enough to keep up to date periodically, and no big deal if it goes out of date for a while. and if nobody likes to fix it - we delete it 😄

INDEX.md

danmoseley · 2021-03-24T01:56:00Z

accepted/2020/workloads/workload-resolvers.md


+**PM** [Rich Lander](https://github.com/richlander)
+
+// FIXME: do these count as PMs/Devs?


PM, Dev, Dev, but I don't think it matters

danmoseley · 2021-03-24T01:56:07Z

accepted/2020/workloads/workload-manifest.md


+**PM** [Rich Lander](https://github.com/richlander)
+
+// FIXME: do these count as PMs/Devs?


danmoseley · 2021-03-24T01:56:17Z

accepted/2020/workloads/workloads.md

+
+**PM** [Rich Lander](https://github.com/richlander)
+
+// FIXME: do these count as PMs/Devs?


PM, Dev Dev

danmoseley · 2021-03-24T01:58:28Z

@terrajobst do you feel the distinction between dev and PM in the template is important? not all documents have both, and even if they do, the roles are blurred. I think the template ought to just prompt for a list of stakeholders or owners, whatever their roles. the key requirement is: include all stakeholders and record who they are!

terrajobst · 2021-03-24T02:01:54Z

seems easy enough to keep up to date periodically, and no big deal if it goes out of date for a while

Sure, let's try and see

do you feel the distinction between dev and PM in the template is important?

No. In fact, let's change the template and call it "owner". I'll fix that.

danmoseley · 2021-03-24T02:08:53Z

@omajid do you feel like a follow up change that merges Dev/PM into Owners? If not LMK and I can do it.

omajid · 2021-03-24T02:10:35Z

I am happy to do it, but it might take a few days.

jeffhandley · 2021-03-24T02:22:46Z

I'm late to the review

@terrajobst Since we recently started adding documents into accepted that are actually in DRAFT status, I wonder if we could also adjust this index to correct the "proposed" vs. "accepted" problem by deemphasizing the folder and instead adding a draft/proposed/accepted/rejected state column to the index. What do you think?

akoeplinger · 2021-03-24T12:08:49Z

We should probably update https://github.com/dotnet/designs#creating-a-proposal to add a step 3. Add your spec to INDEX.md

This was suggested here: dotnet#190 (comment)

jkotas · 2021-03-29T20:11:45Z

INDEX.md

+| 2021 | [Designs](accepted/2021/statics-in-interfaces/designs/README.md) | [Immo Landwerth](https://github.com/terrajobst) |
+| 2021 | [Requirements](accepted/2021/statics-in-interfaces/requirements/README.md) | [Immo Landwerth](https://github.com/terrajobst) |
+| 2021 | [Scenarios](accepted/2021/statics-in-interfaces/scenarios/README.md) | [Immo Landwerth](https://github.com/terrajobst) |
+| 2021 | [Statics in Interfaces](accepted/2021/statics-in-interfaces/README.md) | [Immo Landwerth](https://github.com/terrajobst) |


Static in interfaces are split over multiple documents. It is not clear by looking at the index that all these 4 documents are for static in interfaces.

Thanks for catching this! Do you think it makes more sense to have a single entry for "Statics In Interfaces" or should we list the individual sub-designs with a prefix like "Statics In Interfaces": "Statics In Interfaces: Requirements", "Statics In Interfaces: Scenarios" and "Statics In Interfaces: Designs"?

I recommend just a single entry for these design that are being spread over multiple documents--just pointing to the top-level README for them.

I think it would make sense to have just a single entry for Statics in Interfaces. The top level Statics in Interfaces doc can have links to the other ones.

I would opt for a process that can be easily generated with @omajid's update script. Leaving designs out is probably harder than, say, a prefix notation.

The script uses a heuristic to separate main designs from subdesigns: If the document lists a PM/Dev (soon Owner), then the document is treated as a main (or top-level) design.

For Statics In Interfaces, it sounds like the main design is accepted/2021/statics-in-interfaces/README.md and the rest are the components. If we removed PM/Dev from those documents, the scripts will just ignore them.

(I also think it makes sense to do anyway: there aren't separate Owners for the Design vs Requirements vs Scenarios, are there?)

Alternatively, I can fix the script to ignore a certain level of nesting as sub-designs and only look for top-level documents.

omajid force-pushed the design-index branch 12 times, most recently from 19ccc9a to 3f0eff7 Compare March 20, 2021 22:19

omajid marked this pull request as ready for review March 20, 2021 22:22

omajid commented Mar 20, 2021

View reviewed changes

INDEX.md Outdated Show resolved Hide resolved

omajid force-pushed the design-index branch from 3f0eff7 to 7651343 Compare March 22, 2021 01:40

danmoseley requested a review from terrajobst March 22, 2021 05:36

omajid force-pushed the design-index branch from 7651343 to 7daa713 Compare March 24, 2021 00:54

omajid force-pushed the design-index branch from 7daa713 to 742e9ea Compare March 24, 2021 00:56

danmoseley reviewed Mar 24, 2021

View reviewed changes

INDEX.md Outdated Show resolved Hide resolved

Update INDEX.md

60d76db

danmoseley reviewed Mar 24, 2021

View reviewed changes

terrajobst approved these changes Mar 24, 2021

View reviewed changes

terrajobst merged commit 1c503a7 into dotnet:main Mar 24, 2021

omajid added a commit to omajid/dotnet-designs that referenced this pull request Mar 28, 2021

Convert from Dev/PM roles to simple Owner

690ae9c

This was suggested here: dotnet#190 (comment)

omajid mentioned this pull request Mar 28, 2021

Convert from Dev/PM roles to simple Owner #194

Closed

jkotas reviewed Mar 29, 2021

View reviewed changes

maryamariyan mentioned this pull request Apr 9, 2021

Compile-time source generation for structured log messages #195

Merged

5 tasks


		PM [Rich Lander](https://github.com/richlander)

		// FIXME: do these count as PMs/Devs?

Add a design index #190

Add a design index #190

Uh oh!

Conversation

omajid commented Mar 19, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danmoseley commented Mar 19, 2021

Uh oh!

danmoseley commented Mar 19, 2021

Uh oh!

mhutch commented Mar 19, 2021

Uh oh!

omajid commented Mar 19, 2021

Uh oh!

omajid commented Mar 20, 2021

Uh oh!

Uh oh!

danmoseley commented Mar 22, 2021

Uh oh!

omajid commented Mar 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

terrajobst commented Mar 24, 2021

Uh oh!

danmoseley commented Mar 24, 2021

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danmoseley commented Mar 24, 2021

Uh oh!

terrajobst commented Mar 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danmoseley commented Mar 24, 2021

Uh oh!

omajid commented Mar 24, 2021

Uh oh!

jeffhandley commented Mar 24, 2021

Uh oh!

akoeplinger commented Mar 24, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

omajid Mar 29, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terrajobst Mar 29, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

omajid commented Mar 19, 2021 •

edited

Loading

omajid commented Mar 24, 2021 •

edited

Loading

terrajobst commented Mar 24, 2021 •

edited

Loading

omajid Mar 29, 2021 •

edited

Loading

terrajobst Mar 29, 2021 •

edited

Loading