dotnet / dotnet/docfx

[Bug] The `branch:` lines in metadata show the branch name, but they should be commit IDs

Open
#10,656 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

When running `docfx metadata`, the resulting .yaml files have entries that include `branch: main` in their `source` sections:

```yaml
source:
remote:
path: src/xunit.v3.core/AssemblyFixtureAttribute.cs
branch: main
repo: https://github.com/xunit/xunit
id: AssemblyFixtureAttribute
path: ../src/xunit.v3.core/AssemblyFixtureAttribute.cs
startLine: 16
```

When generating documentation, the source links in the docs then point to the `main` branch source file rather than a permalink to the file that was used to build the documentation.

I expect these `branch:` entries to use the Git commit ID so that generated links are permanent.

Looking at [GitUtility](https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/Git/GitUtility.cs) I cannot simply override with a single environment variable, because my source uses Git submodules.

The only way to "fix" this today is a massive manual search and replace that is cognizant of which repo should get which commit ID. (Alternatively, if I run `docfx metadata` locally, outside of a CI environment, the generation is broken in a different way: it gets the `branch:` entries correct for the primary repo, but for some reason stops providing remote source information for the submodules, and includes broken local paths like `C:\Dev\...` instead of the relative paths like seen above. This leaves me with the search & replace as the only available mechanism.)

Is there a way to just tell `docfx metadata` that I would prefer commit IDs, and have it also track properly into Git submodules? I have not found an obvious switch or config option.

As an example of how I expect the metadata to appear, compare:

[https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.AssemblyFixtureAttribute.yml#L125-L132](https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.AssemblyFixtureAttribute.yml#L125-L132) (primary repo)

```yaml
source:
remote:
path: src/xunit.v3.core/AssemblyFixtureAttribute.cs
branch: ccd27e9792077b9ee82f40320c6f414e6a0338de
repo: https://github.com/xunit/xunit
id: .ctor
path: ../src/xunit.v3.core/AssemblyFixtureAttribute.cs
startLine: 16
```

[https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.Assert.yml#L333-L340](https://github.com/xunit/api.xunit.net/blob/7aefd8d12177bac19f87aed0773ecac7ed603a92/metadata/v3/2.0.2/Xunit.Assert.yml#L333-L340) (submodule)

```yaml
source:
remote:
path: Assert.cs
branch: 892ce2e9656c2424790b1cd3a209e9d42882e62d
repo: https://github.com/xunit/assert.xunit
id: .ctor
path: ../src/xunit.v3.assert/Asserts/Assert.cs
startLine: 28
```

You can see the generated content with appropriate external links:

https://api.xunit.net/v3/2.0.2/v3.2.0.2-Xunit.AssemblyFixtureAttribute.-ctor.html#v3_2_0_2_Xunit_AssemblyFixtureAttribute__ctor_System_Type_

https://api.xunit.net/v3/2.0.2/v3.2.0.2-Xunit.Assert.-ctor.html

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.