Onboard DocFX as a formal .NET Foundation project

[markjulmar]

1.   General Information

Project Name: DocFX

License: MIT

Contributor (Company, Organization or individual name(s)): Microsoft

Existing OSS Project? (Yes/No): Yes

Source Code URL: dotnet/docfx: Static site generator for .NET API documentation. (github.com)

Project Homepage URL (if different): DocFX - static documentation generator | DocFX website (dotnet.github.io)

Project Transfer Signatories:
Full legal name and email address required of the individual(s) with the authority to transfer or contribute the project to the .NET Foundation. Note that if you'd prefer not to include this in the public application, it can be submitted via e-mail to [email protected] (referencing this issue number).

Mark Colin Smith, [email protected]
Yufei Huang, [email protected]

2.   Description

Please provide a brief statement about your project in terms that are understandable to the target consumer of the library or project, i.e. an elevator pitch for the project:

DocFX is a cross-platform, flexible, and customizable static site generator capable of creating documentation pages from Markdown and YAML complete with different layouts, a TOC, and reference APIs created from various languages. This project has been used to create several websites including the original docs.microsoft.com.

Please provide a 1 sentence (<140 character) summary of your project to help users when searching the .NET Foundation projects

DocFX makes it extremely easy to generate your developer hub with a landing page, API reference, and conceptual documentation, from a variety of sources.

3.   Project Governance

Please complete this section about who will be maintaining the open source project and how it will run.
Project Lead:
(Who is the primary contact point for the community and the .NET Foundation when discussing governance of the project.)

Name: Mark Smith
Email: [email protected]
GitHub Profile URL: https://github.com/markjulmar

Committers:

Which individuals have commit / write access to the repository, what is their GitHub ID and who is their employer (if contributions are on behalf of an employer)

Yufei Huang [email protected] yufeih (Yufei Huang) (github.com)
Liangying Wei [email protected] vicancy (Liangying.Wei) (github.com)
Mark Smith [email protected] markjulmar (Mark Smith) (github.com)

Contributions are not on behalf of Microsoft.

Governance Model:

Please describe how new code changes are proposed to the project, how those changes are reviewed and how a decision is made to accept proposed changes. Also describe the process for identifying and appointing new committers.

We use the GitHub discussions area to engage with the community, answer questions, discuss pull requests, and provide some direction for the project. Historically, a lot of direction has been decided by the docs.microsoft.com engineering and PM teams as this was a core tool used by that site, but our goal is to shift it to the community as part of this oversight change.

In the past, new committers have been decided by activity and the project administrators.

CLA

If already an OSS project, was a Contribution License Agreement in place for contributions accepted? How does the project check who has signed one?

Yes, we’re using the .NET Foundation CLA - .NET Foundation Contributor License Agreement (dotnetfoundation.org)

CLA Notification Alias
Provide an email address that will receive CLA related notifications from the .NET Foundation CLA automation

I’m not sure – I think we got the CLA because the project is hosted in the https://github.com/dotnet organization.

Assignment Model. Under the .NET Foundation assignment model, project ownership and other intellectual property is assigned to the .NET Foundation and the .NET Foundation agrees to grantback a license to the contributor(s).

Contribution Model. Under the .NET Foundation contribution model, a project retains ownership of the copyright, but grants the .NET Foundation a broad license to the project’s code and other intellectual property. The project also confirms that the project’s submissions to .NET Foundation are its own original work (there are also instructions for any third party materials that might be included).

4.   Repository Layout

The .NET Foundation host guidance for new projects and details on recommended structure here:
https://github.com/dotnet/home/tree/master/guidance

Note that the open source repository should be the master where changes are made by the core development team using the same PR process that is used for non-committer contributions.

Please define below any changes you would want to make to your repositories as part of the process of joining the .NET Foundation

We have a new version under development (V3) that isn’t ready for release but has a completely different folder structure for building the tool. Eventually, we’ll shift to this new layout.
Also, we will likely need to update the documentation files (README, SECURITY, CONTRIBUTING, etc.) to change some of the references to Microsoft as this was originally owned and maintained by a Microsoft engineering team (but published under an MIT license). We would like some guidance on this if possible – what we should do, and what is required.

5. Eligibility Criteria

Please complete the following for your project

• The project is built on the .NET platform and/or creates value within the .NET ecosystem.

• Yes
• No

• The project produces source code for distribution to the public at no charge.

• Yes
• No

• The project's code is easily discoverable and publicly accessible (preferably on GitHub).

• Yes
• No

• The project contains a build script that can produce deployable artifacts that are identical to the official deployable artifacts, with the exception of code signing (Exception may be granted for strong name keys, though strongly encouraged to be committed. Exception relies on OSS signing being in the build script for public builds).

• Yes
• No

• When applicable, project must use reproducible build settings in its toolchain.

• Yes
• No

• The project uses Source Link.

• Yes
• No

• The project uses either embedded PDBs or publish symbol packages to NuGet (if applicable).

• Yes
• No

• The project code signs their artifacts as appropriate.

• Yes
• No

• The project organization has 2FA enabled. Requiring 2FA must be done as part of onboarding if not already enabled.

• Yes
• No

• Libraries that are mandatory dependencies of the project are offered under a standard, permissive open source license which has been approved by the .NET Foundation (exceptions include a dependency that is required by the target platform where no alternative open source dependency is available such as the .NET Framework or a hardware specific library).

• Yes
• No

• Committers are bound by a Contributor License Agreement (CLA) and/or are willing to embrace the .NET Foundation's CLA when the project becomes a Member.

• Yes
• No

• The copyright ownership of everything that the project produces is clearly defined and documented.

• Yes
• No

• The project has a public issue tracker where the status of any defect can be easily obtained.

• Yes
• No

• The project has a published Security Policy.

• Yes
• No

• The project has a home page which provides high level information about its status and purpose.

• Yes
• No

• The project has a public communication channel where community members can engage with maintainers.

• Yes
• No

• The project has a publicly available location where members can review and contribute to documentation.

• Yes
• No

6.   PR Plan

Please summarize the public relations plan for the announcement when joining the foundation (and releasing as open source if appropriate). What is the main story we wish to promote, through what channels, what issues should we be aware of?  For significant news events then please also work with your .NET Foundation contact to ensure a full PR plan is developed.

DocFX was a core tool used to create all the pages published to docs.microsoft.com – however we’ve since shifted to a more dynamic rendering model and our dependency on this site generator has been reduced to just the parsing code. As such, the primary engineering team responsible for Learn is no longer contributing formally to this project, but we recognize that there are a lot of other teams and customers using this tool, so we'd like to keep expanding it's use for the community. As such, we’ll create an announcement of shifting the project to a contributor-maintained model under the .NET Foundation umbrella where it will continue to evolve and be supported by the existing maintainers that are still passionate about its development.

We will make this announcement on the GitHub site as part of the README and RELEASENOTE and place a banner on the public site created for the tool as part of a formal update to the public documentation page for the project.

7.   Infrastructure Requirements

Please describe any infrastructure requirements for the project. For example, how will build servers be operated? Any web hosting or service hosting requirements? Do we need to set up SSL certificates or provide Authenticode Code Signing arrangement for releases?

The tool can be built with a standard .NET install and we can produce the release packages with GitHub actions. There are no web hosting or service hosting requirements for DocFX itself.

We do currently sign with a Microsoft-owned key which we'd like to replace with a .NET Foundation key.

8.   Additional Notes

Please provide any additional information required or use this area for notes during the onboarding process. If this open source project has similarities with any other projects in this space then please detail them and why this project is different. If there are any potential issues that you feel the project might need help with early on then also state them here and discuss with your .NET Foundation Contact.

DocFX is like other static site generators such as Docusaurus and Jekyl. The key difference with this tool is a more flexible template system as well as the ability to plug in extensions and other Markdown parsers as well as do replacements of sections based on runtime criteria. It also can produce other output types such as JSON and PDF.

As mentioned above, we have an updated version started in a branch – there is still significant work remaining to both test this version as well as provide backward compatibility with some features that got broken accidentally as part of the refactor.

[sbwalker]

Project was recommended for approval by Project Committee... will be reviewed by BOD in Feb Board meeting

[yufeih]

The project actually uses SourceLink

[markjulmar]

The project actually uses SourceLink

Thanks Yufei - updated the request.

[sbwalker]

BOD meeting today - BOD voted for DocFX to be approved as a Member Project. @ChrisSfanos will be in touch shortly for onboarding.

[ChrisSfanos]

Hello! We will be using the following checklist to onboard DocFX to the .NET Foundation

CLA

• Project Agreement Signing via DocuSign
• CLA Onboarding

Project Onboarding

• Public Announcement via the .NET Foundation site/etc
• Joining the Project leader mailing list
• Joining the Project leader Slack channel
• Updating license/copyright in the repo + updating file headers
• Reviewing the .NET Foundation Code of Conduct
• Add Project to the .NET Foundation project list
• Project layout cleanup (as appropriate)
• README Guidance updates
• Project website updates (outside of GitHub)
• Enable two-factor authentication (2FA) for GitHub organization and all users

[ChrisSfanos]

agreement is out for signing

[yufeih]

@ChrisSfanos I have signed the agreement together with @markjulmar. What additional steps do we need to move the process forward.

[ChrisSfanos]

Thanks! I'm going to send you an email covering the CLA onboarding a separate one detailing the set of remaining steps above

[ChrisSfanos]

Never mind on the CLA - the project is already in /dotnet/ so it's covered

[KalleOlaviNiemitalo]

According to dotnet-foundation/website#1134 it was already a .NET Foundation project.

Libraries that are mandatory dependencies of the project are offered under a standard, permissive open source license which has been approved by the .NET Foundation (exceptions include a dependency that is required by the target platform where no alternative open source dependency is available such as the .NET Framework or a hardware specific library).

There have been dependencies on GNU AGPL licensed iTextSharp and Json.NET Schema; see dotnet/docfx#4250 and dotnet/docfx#7663. The schema library was replaced in v2.63.0 dotnet/docfx#8418 but AFAICT the iTextSharp dependency is still there and is shipped in the docfx tool package.

[ChrisSfanos]

Hi @KalleOlaviNiemitalo - yes per the comments in that issue there is work to bring the repos up to the same standards for all .NET Foundation projects

Is the 2nd part a question? I'm not exactly sure what you are asking?

[yufeih]

@ChrisSfanos may the "project website" link be updated to https://dotnet.github.io/docfx/ ?

Edit:

Maybe it depends on "Project website updates (outside of GitHub)"

[ChrisSfanos]

Hi @yufeih - I'm sorry I'm not exactly sure what you are asking? If you want to reach me on Teams if that's easier we can do that too

[ChrisSfanos]

Hi @yufeih - circling back - looks like we didn't get to wrap up all the work items. Can you let me know the latest status?

Thanks!