Runtime: Lacking documentation of Maestro/DARC for contributors
There seem to be legitimate scenarios where contributors need to be aware of existence of the Maestro/Maestro++ bots and how the dependency flow between various .NET Core repositories work. While there's some documentation in the arcade repository and the buildtools repository it's mostly targeted to maintainers and not for regular contributors. It may be worth extending the documentation to cover common scenarios that are experienced by the contributors and answered in the pull requests all over again. Below is a list of topics that I found to be lacking, but it is by no means exhaustive.
Why should I care about Maestro at all?
Because CoreCLR, CoreRT, UWP and CoreFX runtime reside in different repositories, which are bound together by referencing specific versions of the other dependent repositories. Tests for runtime behavior reside in CoreFX repository. Thus any change to the runtime or System.Private.CoreLib which has to be tested needs two separate changes - one in the runtime repository to implement the new behavior and other in the CoreFX repository to introduce or update the tests. Both changes are submitted as separate pull requests and they can land only in specific order. First, the runtime change has to land, then Maestro needs to update CoreFX dependencies with the new runtime dependency version and only then the CoreFX test PR can land. The Azure Pipelines tests have to be re-run when that happens, it can be triggered by "/azp run corefx-ci".
How do I find out that dependency was updated and my test PR is good to go?
Usually Maestro and Maestro++ jobs are scheduled to run at least once a day, you should see a pull request like https://github.com/dotnet/corefx/pull/36357 or https://github.com/dotnet/corefx/pull/36363.
Why is there Maestro and Maestro++? What is the difference?
Maestro comes from dotnet/buildtools and it's the original version of the tool that is no longer used for new projects. It's still used by CoreRT and UWP runtimes that are referenced from CoreFX for continuous integration. Maestro++ is the new tool from dotnet/arcade. Maestro++ has merge policies, so it can be set up to auto-merge if all CI tests pass and thus make the dependency flow more seamless.
My runtime PR was merged X days ago, but the dependency was not picked up by CoreFX and my test PR still fails. What should I do?
Open issue here, tag some specific people perhaps?
Some less relevant questions I came up with, but which may still deserve answers:
Why is CoreFX package version 4.6.x-something-buildNumber for .NET Core 3.0? How are the versions related? Where do they come from?
Where's documentation for eng/update-dependencies.cmd? Is it still relevant for Maestro++ or is it just Maestro thing?
/cc @karelz @MarcoRossignoli
filipnavara
All 16 comments
Some thought
My runtime PR was merged X days ago, but the dependency was not picked up by CoreFX and my test PR still fails. What should I do?
Is there a way to check throught commit hash if update is included?
I've got this issue a lot of time with ProjectN and some team member re-run test "at some(obscure to me) point" and works.
MarcoRossignoli
on 27 Mar 2019
Is there a way to check throught commit hash if update is included?
Maybe. I usually look at history of https://github.com/dotnet/corefx/blob/master/eng/dependencies.props. If it was updated after my CoreRT change was merged then I re-run the tests.
filipnavara
on 27 Mar 2019
Oh yes I did it in past, I think this could be in "that" docs, if no better way exists.
MarcoRossignoli
on 27 Mar 2019
There must be better ways but if you ildasm the corelib that is restored when you build corefx it includes the coreclr hash it comes from, in itsmetadata.
danmosemsft
on 27 Mar 2019
, in itsmetadata
attribute?
MarcoRossignoli
on 27 Mar 2019
cc @wtgodbe @safern @ericstj
karelz
on 27 Mar 2019
Does it makes sense to just link it to arcade since we鈥檙e not the owners of the tool and that way we don鈥檛 have to keep updating the docs if something changes?
safern
on 27 Mar 2019
Does it makes sense to just link it to arcade since we鈥檙e not the owners of the tool and that way we don鈥檛 have to keep updating the docs if something changes?
The Arcade docs are not really targeting contributors of the .NET repositories. They describe how to set it up, how to maintain it and lots and lots of technical stuff. Most CoreFX/CoreCLR contributors don't need that. It's nice to link to it, but there are topics that are just not covered there. What contributors usually need to understand are the effects of Maestro/DARC for their workflow (see my first question in the intial post).
filipnavara
on 27 Mar 2019
I absolutely agree. We need to explain how our dependencies flow and what is needed in perspective of corefx. We should describe what triggers a maestro PR and how often they are created. We should also outline that manual updates can be triggered by the infra-group members if desired.
ViktorHofer
on 27 Mar 2019
The Arcade docs are not really targeting contributors of the .NET repositories. They describe how to set it up, how to maintain it and lots and lots of technical stuff. Most CoreFX/CoreCLR contributors don't need that. It's nice to link to it, but there are topics that are just not covered there. What contributors usually need to understand are the effects of Maestro/DARC for their workflow (see my first question in the intial post).
Makes sense.
safern
on 28 Mar 2019
Here are the steps to manually apply an update.
https://github.com/dotnet/arcade/blob/b0c930c2b44acd03671552f52b925183db0fc8ea/Documentation/Darc.md#setting-up-your-darc-client
https://github.com/dotnet/arcade/blob/b0c930c2b44acd03671552f52b925183db0fc8ea/Documentation/Darc.md#update-dependencies
Agree we should have some docs in the repo.
ericstj
on 22 May 2019
@ViktorHofer @safern @ericstj is there a simple way to know if corelib used corefx contains coreclr commit? The @danmosemsft's idea ([assembly: AssemblyInformationalVersion("3.0.0-preview6.19277.72+419b46fc7d0fe0659e7ab521c222b7c921b36e35")]) works but it's a bit tricky, maybe some dependences metadata file contains already last commit.
MarcoRossignoli
on 29 May 2019
The AssemblyInformationalVersion is the easiest way to identify of which commit a given assembly is built from (edit: in corefx and coreclr).
ViktorHofer
on 29 May 2019
You could always look at Version.Details.xml file in corefx and that will contain the commit sha that the dependencies were built from. For example, corefx master currently uses a corelib that its last commit was:
safern
on 31 May 2019
https://devblogs.microsoft.com/dotnet/the-evolving-infrastructure-of-net-core/ is great write up on how things work and why are they done that way!
filipnavara
on 19 Jun 2019
Closing as fixed by @MattGal's blog post.
ViktorHofer
on 23 Jun 2019
Related issues
nalywa
路
3Comments
jchannon
路
3Comments
btecu
路
3Comments
chunseoklee
路
3Comments
v0l
路
3Comments