From ef5af79b542083f4a0610295d00d41b42ee8ca73 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 16 Apr 2019 10:29:10 -0700 Subject: [PATCH 1/7] Add FST-1008 --- ...FST-1008-publish-fcs-from-upstream-repo.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 tooling/FST-1008-publish-fcs-from-upstream-repo.md diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md new file mode 100644 index 00000000..e563a25c --- /dev/null +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -0,0 +1,58 @@ +# FST 1008 Publish FCS from the dotnet/fsharp repository + +This RFC proposes that we publish the [FSharp.Compiler.Service](https://www.nuget.org/packages/FSharp.Compiler.Service/) package from the main F# development repository (`dotnet/fsharp`) and archive the [current downstream repository](https://github.com/fsharp/fsharp.compiler.service). + +## Publishing the package from dotnet/fsharp + +### Signing + +For starters, as per Microsoft policy, any official package considered to be a part of the F# product must be signed: + +* The binaries must be signed by Microsoft signing keys +* The package itself must be signed by Microsoft signing keys + +This would be the same as FSharp.Core today. + +### Prerelease usage + +The F# build would produce a signed FSharp.Compiler.Private package. This would be accessible in a build artifacts directory for anyone looking to build this package against a particular branch of the F# codebase. + +Additionally, Microsoft will publish a nightly feed on MyGet where a new package would be published every time there is a signed F# build. + +These two avenues for consuming a prerelease version of the package should be satisfactory for all tooling authors and those looking to use the package for other purposes. + +## Package ownership + +We propose that package ownership follows the same model as [FSharp.Core](https://www.nuget.org/packages/FSharp.Core/) - namely, it has two official owners: Microsoft and fsharporg. Each of these owners are considered groups where individuals can be added and removed. In this case, we would expect current non-Microsoft maintainers to be members of the fsharporg group so that they can manage the package itself should a Microsoft employee not be available to do so. + +The one quirk here, when compared with the current state of FSharp.Compiler.Service, is that only Microsoft employees would be able to ensure new _binaries_ are able to be produced when needed. In other words, members of the fsharporg group can publish/delist/etc. the package itself, including uploading a new package from the nightly feed, but they cannot actually update the binaries independently of the output of the signed build. We don't see this as an issue in practice because the nightly feed will always be the most up to date build of the bits needed in the package itself, but it is worth calling out. + +## Documentation and webpage updates + +Today, the FSharp.Compiler.Service [website](http://fsharp.github.io/FSharp.Compiler.Service/) has useful documentation for people who are looking to get started with using the service. This webpage must be capable of being produced and updated from the `dotnet/fsharp` repository. There are a few proposed variations on the URL: + +* The same as before: `http://fsharp.github.io/FSharp.Compiler.Service/` +* Using `dotnet`: `http://dotnet.github.io/FSharp.Compiler.Service/` +* Using `dotnet/fsharp`: `http://dotnet.github.io/fsharp/FSharp.Compiler.Service/` + +The first is preferred so that links need not be updated across the web, so that is the priority to get. But if it cannot be done, they are listed in order of preference. + +## Archiving the FSharp.Compiler.Service repository + +Once the `dotnet/fsharp` repository is set up to publish nightlies of the FSharp.Compiler.Service package and the NuGet package itself has been set up as documented above, the process for archiving the FSharp.Compiler.Service repository can begin. It's not as simple as merely arching the repository: + +### Migrating issues + +At the time of writing, there are 73 open issues. Each will need to be determined to be valid or invalid. If they are valid, they must be moved to `dotnet/fsharp` and tagged appropriately. There should be 0 remaining issues open in this repository. + +### Migrating pull requests + +At the time of writing, there are 3 open pull requests. If they are valid, they should be moved to `dotnet/fsharp` and closed in the FSharp.Compiler.Service repository. There should be 0 remaining pull requests open. + +### README and repo description updates + +The README must be modified to state clearly that this repository is archived, all open issues have been moved to `dotnet/fsharp`, and any new issues or PRs should be filed there. + +Additionally, we should retain the historical context of this repository to ensure that we don't lose any of the rich history it has developed over the years. + +Finally, once all of the above is completed, we can archive the repository. \ No newline at end of file From e24a714ba2b0bf32891496a6c2523feb5cd91284 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 16 Apr 2019 10:38:53 -0700 Subject: [PATCH 2/7] private <> service --- tooling/FST-1008-publish-fcs-from-upstream-repo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index e563a25c..bfa500c1 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -15,7 +15,7 @@ This would be the same as FSharp.Core today. ### Prerelease usage -The F# build would produce a signed FSharp.Compiler.Private package. This would be accessible in a build artifacts directory for anyone looking to build this package against a particular branch of the F# codebase. +The F# build would produce a signed FSharp.Compiler.Service package. This would be accessible in a build artifacts directory for anyone looking to build this package against a particular branch of the F# codebase. Additionally, Microsoft will publish a nightly feed on MyGet where a new package would be published every time there is a signed F# build. From 608981c62eee9bd5fdf04a346d1241324f4486dc Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 16 Apr 2019 10:42:57 -0700 Subject: [PATCH 3/7] Address compatibility and versioning --- tooling/FST-1008-publish-fcs-from-upstream-repo.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index bfa500c1..349db999 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -55,4 +55,13 @@ The README must be modified to state clearly that this repository is archived, a Additionally, we should retain the historical context of this repository to ensure that we don't lose any of the rich history it has developed over the years. -Finally, once all of the above is completed, we can archive the repository. \ No newline at end of file +Finally, once all of the above is completed, we can archive the repository. + +## Compatibility and versioning + +Despite the package being at version `28.0.0` at the time of writing, it's best to think of it as version `0.28`. It is not binary compatible and is subject to many breaking changes. The FCS API itself is likely to undergo more changes in the future, and consumers of that API will have to adjust to those changes. This is the norm today, and we expect it to continue for quite some time. Given this, the compatibility and versioning rules are: + +* The binary in the package is **not** binary compatible and will change +* The package will follow semantic versioning, where any major version change indicates a possible breaking change + +In the future, the FCS APIs may stabilize and binary compatibility may be enforced. But that is at an unknown time long in the future. From c6c2280d7aaa32d16e4b74e8dd3af53200ff5409 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 16 Apr 2019 13:17:39 -0700 Subject: [PATCH 4/7] Update FST-1008-publish-fcs-from-upstream-repo.md --- tooling/FST-1008-publish-fcs-from-upstream-repo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index 349db999..7b60ecd6 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -39,7 +39,7 @@ The first is preferred so that links need not be updated across the web, so that ## Archiving the FSharp.Compiler.Service repository -Once the `dotnet/fsharp` repository is set up to publish nightlies of the FSharp.Compiler.Service package and the NuGet package itself has been set up as documented above, the process for archiving the FSharp.Compiler.Service repository can begin. It's not as simple as merely arching the repository: +Once the `dotnet/fsharp` repository is set up to publish nightlies of the FSharp.Compiler.Service package and the NuGet package itself has been set up as documented above, the process for archiving the FSharp.Compiler.Service repository can begin. It's not as simple as merely archiving the repository, however: ### Migrating issues From 0fa61062a858e61980d8b5b9bc51e5d2223ba553 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Wed, 17 Apr 2019 07:58:54 -0700 Subject: [PATCH 5/7] Add fable and build/deps section --- ...FST-1008-publish-fcs-from-upstream-repo.md | 40 +++++++++++++++---- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index 7b60ecd6..85ad12b9 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -1,6 +1,6 @@ # FST 1008 Publish FCS from the dotnet/fsharp repository -This RFC proposes that we publish the [FSharp.Compiler.Service](https://www.nuget.org/packages/FSharp.Compiler.Service/) package from the main F# development repository (`dotnet/fsharp`) and archive the [current downstream repository](https://github.com/fsharp/fsharp.compiler.service). +This RFC proposes that we publish the [FSharp.Compiler.Service](https://www.nuget.org/packages/FSharp.Compiler.Service/) (FCS) package from the main F# development repository (`dotnet/fsharp`) and archive the [current downstream repository](https://github.com/fsharp/fsharp.compiler.service). ## Publishing the package from dotnet/fsharp @@ -15,7 +15,7 @@ This would be the same as FSharp.Core today. ### Prerelease usage -The F# build would produce a signed FSharp.Compiler.Service package. This would be accessible in a build artifacts directory for anyone looking to build this package against a particular branch of the F# codebase. +The F# build would produce a signed FCS package. This would be accessible in a build artifacts directory for anyone looking to build this package against a particular branch of the F# codebase. Additionally, Microsoft will publish a nightly feed on MyGet where a new package would be published every time there is a signed F# build. @@ -25,11 +25,11 @@ These two avenues for consuming a prerelease version of the package should be sa We propose that package ownership follows the same model as [FSharp.Core](https://www.nuget.org/packages/FSharp.Core/) - namely, it has two official owners: Microsoft and fsharporg. Each of these owners are considered groups where individuals can be added and removed. In this case, we would expect current non-Microsoft maintainers to be members of the fsharporg group so that they can manage the package itself should a Microsoft employee not be available to do so. -The one quirk here, when compared with the current state of FSharp.Compiler.Service, is that only Microsoft employees would be able to ensure new _binaries_ are able to be produced when needed. In other words, members of the fsharporg group can publish/delist/etc. the package itself, including uploading a new package from the nightly feed, but they cannot actually update the binaries independently of the output of the signed build. We don't see this as an issue in practice because the nightly feed will always be the most up to date build of the bits needed in the package itself, but it is worth calling out. +The one quirk here, when compared with the current state of FCS, is that only Microsoft employees would be able to ensure new _binaries_ are able to be produced when needed. In other words, members of the fsharporg group can publish/delist/etc. the package itself, including uploading a new package from the nightly feed, but they cannot actually update the binaries independently of the output of the signed build. We don't see this as an issue in practice because the nightly feed will always be the most up to date build of the bits needed in the package itself, but it is worth calling out. ## Documentation and webpage updates -Today, the FSharp.Compiler.Service [website](http://fsharp.github.io/FSharp.Compiler.Service/) has useful documentation for people who are looking to get started with using the service. This webpage must be capable of being produced and updated from the `dotnet/fsharp` repository. There are a few proposed variations on the URL: +Today, the FCS [website](http://fsharp.github.io/FSharp.Compiler.Service/) has useful documentation for people who are looking to get started with using the service. This webpage must be capable of being produced and updated from the `dotnet/fsharp` repository. There are a few proposed variations on the URL: * The same as before: `http://fsharp.github.io/FSharp.Compiler.Service/` * Using `dotnet`: `http://dotnet.github.io/FSharp.Compiler.Service/` @@ -37,9 +37,9 @@ Today, the FSharp.Compiler.Service [website](http://fsharp.github.io/FSharp.Comp The first is preferred so that links need not be updated across the web, so that is the priority to get. But if it cannot be done, they are listed in order of preference. -## Archiving the FSharp.Compiler.Service repository +## Archiving the FCS repository -Once the `dotnet/fsharp` repository is set up to publish nightlies of the FSharp.Compiler.Service package and the NuGet package itself has been set up as documented above, the process for archiving the FSharp.Compiler.Service repository can begin. It's not as simple as merely archiving the repository, however: +Once the `dotnet/fsharp` repository is set up to publish nightlies of the FCS package and the NuGet package itself has been set up as documented above, the process for archiving the FCS repository can begin. It's not as simple as merely archiving the repository, however: ### Migrating issues @@ -47,7 +47,7 @@ At the time of writing, there are 73 open issues. Each will need to be determine ### Migrating pull requests -At the time of writing, there are 3 open pull requests. If they are valid, they should be moved to `dotnet/fsharp` and closed in the FSharp.Compiler.Service repository. There should be 0 remaining pull requests open. +At the time of writing, there are 3 open pull requests. If they are valid, they should be moved to `dotnet/fsharp` and closed in the FCS repository. There should be 0 remaining pull requests open. ### README and repo description updates @@ -65,3 +65,29 @@ Despite the package being at version `28.0.0` at the time of writing, it's best * The package will follow semantic versioning, where any major version change indicates a possible breaking change In the future, the FCS APIs may stabilize and binary compatibility may be enforced. But that is at an unknown time long in the future. + +## Fable and other dialects of F# that use FCS + +[Fable](http://fable.io/) is the most prominent dialect of F#. The Fable tool chain uses a [fork of FCS](https://github.com/fable-compiler/Fable/tree/master/src/fcs-fable) that adds a few things to the codebase to make Fable possible. + +Moving to `dotnet/fsharp` makes this a bit more challenging for Fable maintainers to keep up to date: + +* FCS being a part of the larger repository means there is more churn to keep up with +* The build process for `fcs-fable` is a bit more complicated + +This can be eased by setting up a bot that automatically merges into a fork of `dotnet/fsharp` that Fable would use, but increased churn is clearly a downside even if a bot can automate the routine stuff. + +However, when positive changes for Fable are made to the F# compiler itself, those changes can be absorbed immediately, rather than waiting for a manual merge to a downstream positive. So that is a positive. + +## Build process + +Today, FCS does not require the installation of too many dependencies nor does it require Windows. This is especially important for Fable. + +Given this, building FCS from `dotnet/fsharp` should also require no additional dependencies. It should be as [simple as it is today](https://github.com/Microsoft/visualfsharp/tree/master/fcs#building-testing-packaging-releases) in the current FCS source. + +To reiterate - to build FCS in `dotnet/fsharp`: + +* You should only require an OS that .NET Core can run on; i.e., no Windows-only dependencies +* You should not need to install any machine dependencies to build FCS +* You should be able to edit the FCS source in your editor of choice by opening `FSharp.Compiler.Service.sln` +* You should be able to produce an unsigned `.nupkg` of FCS for personal use \ No newline at end of file From 3f3cc1827acd0d3209898f6bffe9636e67bf1609 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Wed, 17 Apr 2019 09:48:55 -0700 Subject: [PATCH 6/7] feedback --- tooling/FST-1008-publish-fcs-from-upstream-repo.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index 85ad12b9..63054df8 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -89,5 +89,6 @@ To reiterate - to build FCS in `dotnet/fsharp`: * You should only require an OS that .NET Core can run on; i.e., no Windows-only dependencies * You should not need to install any machine dependencies to build FCS +* You should be able to run all FCS tests without machine dpeendencies or a particular OS * You should be able to edit the FCS source in your editor of choice by opening `FSharp.Compiler.Service.sln` * You should be able to produce an unsigned `.nupkg` of FCS for personal use \ No newline at end of file From 05d2251810bf1abaf883a2a69aa38a22734cd1ae Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Wed, 17 Apr 2019 10:09:07 -0700 Subject: [PATCH 7/7] typo --- tooling/FST-1008-publish-fcs-from-upstream-repo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/FST-1008-publish-fcs-from-upstream-repo.md b/tooling/FST-1008-publish-fcs-from-upstream-repo.md index 63054df8..c5a50f0e 100644 --- a/tooling/FST-1008-publish-fcs-from-upstream-repo.md +++ b/tooling/FST-1008-publish-fcs-from-upstream-repo.md @@ -89,6 +89,6 @@ To reiterate - to build FCS in `dotnet/fsharp`: * You should only require an OS that .NET Core can run on; i.e., no Windows-only dependencies * You should not need to install any machine dependencies to build FCS -* You should be able to run all FCS tests without machine dpeendencies or a particular OS +* You should be able to run all FCS tests without machine dependencies or a particular OS * You should be able to edit the FCS source in your editor of choice by opening `FSharp.Compiler.Service.sln` * You should be able to produce an unsigned `.nupkg` of FCS for personal use \ No newline at end of file