Xamarin.forms: Please add instructions for updating docs and creating Nuget files

[adrianknight89]

There is some instruction overlap on Readme.md, Contributing.md, and https://blog.xamarin.com/beginners-guide-contributing-xamarin-forms/ which can be removed. Would love to see an update to these files to remove repetitive information such as not using the private modifier for local fields and methods.

Also, please add instructions for updating docs when a new API is added or an existing one is updated.

It'd also be nice to know how you're generating Nuget files so that we could make them locally for testing purposes. Sometimes, it's difficult to use the Gallery app when it keeps crashing because of the way the landing page is structured. (For example, switching to TabbedPage format and pushing pages on the stack crashes).

Finally, building the solution and/or individual projects in VS 2017 sometimes creates compilation errors especially with respect to XamlGTask,XamlCTask, FixXFCoreAssembly, etc.. What are some things the team is doing to fix them? Would like to see instructions around this also.

[bruzkovsky]

Also, please add instructions for updating docs when a new API is added or an existing one is updated.

I would really love to see some documentation on how you generate the docs too!

It'd also be nice to know how you're generating Nuget files so that we could make them locally for testing purposes

@adrianknight89 have you read this blog post from @davidortinau? https://blog.xamarin.com/building-xamarin-forms-nuget/

Finally, building the solution and/or individual projects in VS 2017 sometimes creates compilation errors especially with respect to XamlGTask,XamlCTask, FixXFCoreAssembly, etc..

Just got stuck with this again today! Do you guys (Xamarin team) also struggle with this a lot or do you have an easy fix for us?

I will also share what I found out today, maybe it will help you with the XamlGTask issue:

Xamarin.Forms.Build.Tasks.csproj has a target named _CopyToNuspecDir. This copies all DLLs from bin to ../.nuspec after build. VS 2017 may decide to lock a DLL that is already present in ../.nuspec and thus prevents it from being overridden, which then result in these ominous errors with XamlGTask. I finally got everything to build after closing VS and git clean -dfx, then rebuild.

[adrianknight89]

@bruzkovsky Thanks for that link. I hadn't seen it before! I think it does have some instructions regarding docs. I'll go over that post tonight. Still, I'd say this issue is still valid as it should be easier for us to find information. Sometimes, it's difficult to jump from URL to URL without getting lost somewhere.

Also, we need how-tos on handling compilation issues.

P.S. I'll try running git clean. :)

[bruzkovsky]

Still, I'd say this issue is still valid as it should be easier for us to find information

I am totally with you!

[adrianknight89]

More info on FixXFCoreAssembly

Severity    Code    Description Project File    Line    Suppression State
Error   MSB4018 The "FixXFCoreAssembly" task failed unexpectedly.
System.IO.FileNotFoundException: Could not find file 'C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\obj\Debug\netstandard1.0\Xamarin.Forms.Core.dll'.
File name: 'C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\obj\Debug\netstandard1.0\Xamarin.Forms.Core.dll'
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share)
   at Mono.Cecil.ModuleDefinition.ReadModule(String fileName, ReaderParameters parameters)
   at Mono.Cecil.AssemblyDefinition.ReadAssembly(String fileName, ReaderParameters parameters)
   at XFCorePostProcessor.Tasks.FixXFCoreAssembly.Execute()
   at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
   at Microsoft.Build.BackEnd.TaskBuilder.<ExecuteInstantiatedTask>d__26.MoveNext() Xamarin.Forms.Core  C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\Xamarin.Forms.Core.csproj    22  

Severity    Code    Description Project File    Line    Suppression State
Error   MSB4018 The "FixXFCoreAssembly" task failed unexpectedly.
System.IO.FileNotFoundException: Could not find file 'C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\obj\Debug\netstandard2.0\Xamarin.Forms.Core.dll'.
File name: 'C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\obj\Debug\netstandard2.0\Xamarin.Forms.Core.dll'
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share)
   at Mono.Cecil.ModuleDefinition.ReadModule(String fileName, ReaderParameters parameters)
   at Mono.Cecil.AssemblyDefinition.ReadAssembly(String fileName, ReaderParameters parameters)
   at XFCorePostProcessor.Tasks.FixXFCoreAssembly.Execute()
   at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
   at Microsoft.Build.BackEnd.TaskBuilder.<ExecuteInstantiatedTask>d__26.MoveNext() Xamarin.Forms.Core  C:\Users\xyz\source\repos\Xamarin.Forms\Xamarin.Forms.Core\Xamarin.Forms.Core.csproj    22  

[adrianknight89]

@davidortinau I was reading the Nuget blog of yours. create-nuget.bat is failing at mkdir commands if directories already exist. I think the script would be more robust if it were to remove the debug folders before creating them empty. Also, NUGET_DIR environment variable must be set with a backslash. This was not on the instructions. AFAIK, nuget.exe is not included with VS and must be downloaded separately.

Also, I believe update-docs-windows.bat is no longer available.

[opcodewriter]

I'd also like to know this

[adrianknight89]

FYI. Looks like updating docs is no longer necessary according to @samhouts as that process is now handled by a separate team. I'll keep this ticket open since there is discussion (and work to be done) on other things.

[PureWeen]

I just created this PR

https://github.com/xamarin/Xamarin.Forms/pull/3605

AFAICT the issue with FixXFCoreAssembly is an msbuild quirk

For some reason the msbuild engine determines that it doesn't need to generate the Xamarin.Forms.Core.dll which then causes the FixXFCoreAssembly to fail

[adrianknight89]

@PureWeen Thanks for fixing that particular issue. :)

[kingces95]

We do not use create-nuget.bat to create nuget files. Go figure. :) The actual script we using during release is squirreled away in our CI system.

I create this bat file for myself to simplify the testing of customer reproductions. I checked it in because it's generally useful. I update it as I discover it's out of date. And as it's not the official nuget generation script it will often be out of date. I'll suffix it with a . to provide a stronger hint this is not officially supported.

[conceptdev]

I would really love to see some documentation on how you generate the docs too!

We use these open-source tools – mdoc and docfx for our API Documentation (along with some proprietary CI stuff, that enables localization and load-balancing, etc and a custom template for the docs.microsoft.com "look"). The script that turns the docs into Intellisense is already visible in the Xamarin.Forms repo.

Also, please add instructions for updating docs when a new API is added or an existing one is updated.

Currently the API docs are not open-source so I don't have anything immediate to share... _however_ we are well along in the process of making this available, at which point we'll include some contribution guidelines.