Starting the PJ schema changes #448

blackdwarf · 2016-05-17T23:28:36Z

This is the starting point for changes to the project.json schema reference document to align it with the schema file. This file is the source of truth for the schema. Another resource is this announcement: aspnet/Announcements#175.

Ideally, we should also add samples to the file for some common scenarios. We should all party on this now.

Fixes #423

/cc @cartermp @mairaw @DamianEdwards

mairaw · 2016-05-17T23:44:13Z

Do we have a link to the issue tracker?

blackdwarf · 2016-05-17T23:54:22Z

Now we do.

svick · 2016-05-18T01:31:27Z

Isn't project.json going away? Doesn't that mean there is not much point to document it extensively?

cartermp · 2016-05-20T17:42:00Z

rebased since some TOC changes were made; now I'll do some updates

richlander · 2016-05-31T06:28:43Z

@svick It's important that we provide good docs for RC2 and RTM to help folks use P.J. The move to csproj will be post-RTM.

blackdwarf · 2016-05-31T12:15:46Z

Post-RTM for the platform. Important to distinguish. For tooling timelines, this means post-Preview 2 of the tooling.

ajaybhargavb · 2016-06-02T18:12:24Z

docs/project-model/project-json-reference.md

+    * [builtIns](#publish-builtins)
+    * [mappings](#publish-mappings)
+* [runtimeOptions](#runtimeoptions)
+    * [gcServier](#gcserver)


Also the structure of runtimeOptions has changed. dotnet/aspnetcore#1418 (comment)

richlander · 2016-06-16T04:36:56Z

@mairaw, @cartermp Are you on point to finish this PR off?

blackdwarf · 2016-06-17T20:24:28Z

@mairaw @cartermp we do need this in a bad way. Can I help somehow to finsih this if you are overloaded?

cartermp · 2016-06-17T21:05:54Z

Updated runtime stuff. The TODOs are what need to be filled in now

mairaw · 2016-06-17T22:06:41Z

@blackdwarf I'm going to add some more missing pieces there and see where we're left.

blackdwarf · 2016-06-17T22:43:46Z

@cartermp @mairaw thanks guys, you rock! :)

mairaw · 2016-06-18T02:47:07Z

Released the file since @blackdwarf said he would work on this next. Can continue to work on this later on.

blackdwarf · 2016-06-19T19:28:12Z

@ajaybhargavb can you please take a look at the current state and comment out what else needs to be done? Thanks!

ajaybhargavb · 2016-06-20T17:20:30Z

docs/project-model/project-json-reference.md

-* [resourceBuiltIn](#resourceBuiltIn)
-* [excludeBuiltIn](#excludeBuiltIn)
+* [namedResource](#namedresource)
+* [packInclude](#packinclude)


namedResource, packInclude and excludeBuiltIn are deprecated and can be removed.

ajaybhargavb · 2016-06-20T17:32:03Z

Looks good. I suggest adding a section that explains the structure to include/exclude files (content aspnet/Announcements#175 (comment)) and then replace the TODOs in compile, embed, copyToOutput, publishOptions and files with a link to this section.

cartermp · 2016-06-23T00:51:12Z

Addressed feedback.

cartermp · 2016-06-23T01:14:30Z

Rebased

svick · 2016-06-23T01:54:09Z

docs/project-model/project-json-reference.md

+For example:
+
+    {
+        "builtIns":[]


If builtIns is supposed to be an object, why is it an empty array here?

ajaybhargavb · 2016-06-24T17:45:46Z

docs/project-model/project-json-reference.md

+#### include
+Type: String or String[] with a globbing pattern.
+
+TODO


All these TODOs need to be replaced as well.

cartermp · 2016-06-24T19:54:55Z

this is going to need another rebase because of the TOC/filename changes; I can get to that later today if it isn't done before then

mairaw · 2016-06-24T20:31:17Z

I'm going to work a bit more on this one now.

mairaw · 2016-06-25T08:46:58Z

@blackdwarf @cartermp @ajaybhargavb I have a new version up. Please take a look. I think we're getting close.

I have a couple of questions though.

There's a TODO in the commands section about investigating actual status. Who can confirm this?
buildoptions\additionalArguments: we have this in the doc but I don't see this in the announcement or in the schema. Should I remove it?
We have a couple of enum types in the schema. Should we list the possible values here? For example, for languageVersion we say ISO-1, ISO-2, 3, 4, 5, 6, or Default and show an example using the value "5". However, the schema shows these values: "csharp1", "csharp2", "csharp3", "csharp4", "csharp5", "csharp6", "experimental". Is that example correct? Wouldn't be better to show these values instead of ISO-1, etc.?
buildOptions\debugType: it's in the schema, but not in the announcement. Should it be included?
buildOptions\xmlDoc: it's in the announcement, not in the schema. Ok to keep it?
buildOptions\preserveCompilationContext - no default?
runtimeOptions: do the following entries really exist?
System.GC.RetainVM, System.Threading.ThreadPool.MinThreads and System.Threading.ThreadPool.MaxThreads
They're not in the schema. If so, what's the default value of RetainVM?
We have references to dnx50 and rc2 in some examples. Do we need to change it? e.g.

    "frameworks": {
        "dnxcore50": {
            "dependencies": {
                "Microsoft.Extensions.JsonParser.Sources": "1.0.0-rc2-23811"
            }
        }
    }

svick · 2016-06-25T09:37:17Z

docs/project-model/project-json-reference.md

-        "summary": "This is my library."
+		"packOptions": {
+			"summary": "This is my library."
+		}
    }


A mix of tabs and spaces is used here and in the following examples (e.g. 4 spaces before {, 2 tabs before "summary").

Though it doesn't really matter, since it seems to render correctly in both GitHub and docfx.

ajaybhargavb · 2016-06-27T22:57:11Z

docs/core/tools/project-json.md

+
+Keys to the object represent destination paths in the output layout.
+
+Values are either a string or an object representing the source path of files to include.  The object represtation can have its own `include`, `exclude`, `includeFiles` and `excludeFiles` sectins"dest/path": "source/path" or "dest/path": { "include": "./src/path" }


Need to correct this, sectins"dest/path"
Also in other options that contain mappings

ajaybhargavb · 2016-06-27T23:11:34Z

⌚

cartermp · 2016-06-30T14:51:19Z

Ready to merge?

mairaw · 2016-06-30T18:47:46Z

Nope @cartermp, I have to incorporate @ajaybhargavb's latest feedback. I'll finish this today. Sorry for the delay. I even have a lovely red tag saying do-not-merge because it's not ready yet. 😄

mairaw · 2016-07-01T03:03:48Z

So here's the feedback on schema. Should I open a bug somewhere @ajaybhargavb?

It's missing buildoptions\additionalArguments
It's missing buildoptions\xmlDoc
buildoptions\preserveCompilationContext is missing the default value
runtimeOptions section is missing the other configProperties (at least the announcement seems to indicate they were added)
maybe it's missing framework and applyPatches inside runtimeOptions

mairaw · 2016-07-01T03:16:52Z

Did a new update. Added debugType and outputName.

Questions still pending:

There's a TODO in the commands section about investigating actual status. Who can confirm this?
We have a couple of enum types in the schema. Should we list the possible values here? For example, for languageVersion we say ISO-1, ISO-2, 3, 4, 5, 6, or Default and show an example using the value "5". However, the schema shows these values: "csharp1", "csharp2", "csharp3", "csharp4", "csharp5", "csharp6", "experimental". Is that example correct? Wouldn't be better to show these values instead of ISO-1, etc.?
runtimeOptions: do the following entries really exist? System.GC.RetainVM, System.Threading.ThreadPool.MinThreads and System.Threading.ThreadPool.MaxThreads They're not in the schema. If so, what's the default value of RetainVM?

/cc @cartermp @blackdwarf @ajaybhargavb

blackdwarf · 2016-07-05T18:29:53Z

@mairaw replied about the commands. Commands are deprecated. There is no way to invoke them any more, really, so I'm not sure if we should keep them around.

@ajaybhargavb what is the correct set ofvalues for the enum?

@schellap can you help us with the various runtimeOptions that are listed above please? What are the things we read in at runtime?

schellap · 2016-07-05T18:44:38Z

@blackdwarf Below link has the list of well-known config options under title "host configuration knobs". The $.runtimeOptions.configProperties can contain any valid JSON key-value: it is used to opt out of specific KB or zero-day updates or allow us to invent one on the fly, etc. Effectively, these keys/values may not be known in advance. Any "string": JSONValue can appear under $.runtimeOptions.configProperties node and will be available to managed code at execution time. Note: these free form key/values will need to be in sync with any schema documentation you write, so it is better to only include what we know for now or link to an evolving page maintained in our repos. I'm calling this out so that someone is not going to do a strict schema validation on this node: $.runtimeOptions.configProperties.

https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/clr-configuration-knobs.md#host-configuration-knobs

ajaybhargavb · 2016-07-05T18:51:14Z

@mairaw, the bugs for missing fields in Schemastore should be filed here https://github.com/SchemaStore/schemastore/issues

@blackdwarf, I am not aware of the correct values for these enums

svick · 2016-07-05T20:11:11Z

@blackdwarf When I add something to "commands", Visual Studio still seems to pick it up and show it as a debug profile. Is that expected?

mairaw · 2016-07-06T07:12:41Z

I've made more changes based on the comments from today. Is this ready to merge?
Also filed the bug for the schema changes.

The only question left was about the enum values.

ajaybhargavb · 2016-07-06T18:02:52Z

Thanks for filing the bug.
after addressing https://github.com/dotnet/core-docs/pull/448/files#r68671400 and figuring out the enum values.
Ping @DamianEdwards, if you want to review this PR.

mairaw · 2016-07-06T18:05:44Z

oh yeah, there are multiple mappings sections with that issue. I'll fix those. Thanks @ajaybhargavb!

mairaw · 2016-07-10T17:09:17Z

Should we review this as-is?
I tried pinging @davidfowl and @piotrpMSFT this week but haven't heard back yet on the enums. Not sure if they're the right folks to ask that.
I believe that's the only thing pending but this version should be much better than the published one.

cartermp · 2016-07-10T17:34:14Z

Let's ship and iterate on future improvements.

mairaw · 2016-07-10T22:49:36Z

🎆

cartermp · 2016-07-11T05:16:59Z

🎉

cartermp force-pushed the pjschema branch from 47b3ac2 to 905002a Compare May 20, 2016 17:41

ajaybhargavb reviewed Jun 2, 2016
View reviewed changes

ajaybhargavb reviewed Jun 20, 2016
View reviewed changes

cartermp force-pushed the pjschema branch from 5e1d4a3 to 9b1793f Compare June 23, 2016 01:14

svick reviewed Jun 23, 2016
View reviewed changes

svick mentioned this pull request Jun 24, 2016

fix typo in project.json reference #607

Closed

ajaybhargavb reviewed Jun 24, 2016
View reviewed changes

svick reviewed Jun 25, 2016
View reviewed changes

ajaybhargavb reviewed Jun 27, 2016
View reviewed changes

mairaw added the do-not-merge label Jun 29, 2016

cartermp mentioned this pull request Jun 30, 2016

Project Model Reference Tasks #325

Closed

7 tasks

incorporated feedback/reorganized buildOptions section

10a28de

fixed second mappings

5a0a803

mairaw removed the do-not-merge label Jul 1, 2016

mairaw mentioned this pull request Jul 5, 2016

Need to update project.json schema SchemaStore/schemastore#201

Closed

additional changes

d4df557

fixed typos

3012493

mairaw merged commit 60bb5a9 into master Jul 10, 2016

mairaw deleted the pjschema branch July 12, 2016 07:41

mairaw mentioned this pull request Jul 14, 2016

[core/tools/project-json.md] Add missing properties to the project.json schema #797

Closed

10 tasks

mairaw mentioned this pull request Oct 5, 2016

Project.json file updates #1071

Merged


		Keys to the object represent destination paths in the output layout.

		Values are either a string or an object representing the source path of files to include. The object represtation can have its own `include`, `exclude`, `includeFiles` and `excludeFiles` sectins"dest/path": "source/path" or "dest/path": { "include": "./src/path" }

Starting the PJ schema changes #448

Starting the PJ schema changes #448

Conversation

blackdwarf commented May 17, 2016 • edited

mairaw commented May 17, 2016

blackdwarf commented May 17, 2016

svick commented May 18, 2016

cartermp commented May 20, 2016

richlander commented May 31, 2016

blackdwarf commented May 31, 2016

ajaybhargavb Jun 2, 2016

Choose a reason for hiding this comment

ajaybhargavb Jun 2, 2016

Choose a reason for hiding this comment

richlander commented Jun 16, 2016

blackdwarf commented Jun 17, 2016

cartermp commented Jun 17, 2016

mairaw commented Jun 17, 2016

blackdwarf commented Jun 17, 2016

mairaw commented Jun 18, 2016

blackdwarf commented Jun 19, 2016

ajaybhargavb Jun 20, 2016 • edited

Choose a reason for hiding this comment

ajaybhargavb commented Jun 20, 2016

cartermp commented Jun 23, 2016

cartermp commented Jun 23, 2016

svick Jun 23, 2016

Choose a reason for hiding this comment

ajaybhargavb Jun 24, 2016

Choose a reason for hiding this comment

cartermp commented Jun 24, 2016

mairaw commented Jun 24, 2016

mairaw commented Jun 25, 2016 • edited

svick Jun 25, 2016

Choose a reason for hiding this comment

ajaybhargavb Jun 27, 2016 • edited

Choose a reason for hiding this comment

ajaybhargavb commented Jun 27, 2016

cartermp commented Jun 30, 2016

mairaw commented Jun 30, 2016

mairaw commented Jul 1, 2016

mairaw commented Jul 1, 2016

blackdwarf commented Jul 5, 2016

schellap commented Jul 5, 2016

ajaybhargavb commented Jul 5, 2016

svick commented Jul 5, 2016

mairaw commented Jul 6, 2016

ajaybhargavb commented Jul 6, 2016

mairaw commented Jul 6, 2016

mairaw commented Jul 10, 2016

cartermp commented Jul 10, 2016

mairaw commented Jul 10, 2016

cartermp commented Jul 11, 2016

blackdwarf commented May 17, 2016 •

edited

ajaybhargavb Jun 20, 2016 •

edited

mairaw commented Jun 25, 2016 •

edited

ajaybhargavb Jun 27, 2016 •

edited