search

dotnet-foundation / projects

This repository is used for onboarding new projects
115 stars 32 forks source link

Onboard DocFX as a formal .NET Foundation project #257

Closed markjulmar closed 1 year ago

markjulmar commented 1 year ago

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 contact@dotnetfoundation.org (referencing this issue number).

Mark Colin Smith, smmark@microsoft.com Yufei Huang, yufeih@microsoft.com

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: mark@julmar.com 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 yufeih@microsoft.com yufeih (Yufei Huang) (github.com) Liangying Wei lianwei@microsoft.com vicancy (Liangying.Wei) (github.com) Mark Smith mark@julmar.com 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

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 commented 1 year ago

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

yufeih commented 1 year ago

The project actually uses SourceLink

markjulmar commented 1 year ago

The project actually uses SourceLink

Thanks Yufei - updated the request.

sbwalker commented 1 year ago

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

ChrisSfanos commented 1 year ago

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

CLA

Project Onboarding

ChrisSfanos commented 1 year ago

agreement is out for signing

yufeih commented 1 year ago

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

ChrisSfanos commented 1 year ago

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

ChrisSfanos commented 1 year ago

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

KalleOlaviNiemitalo commented 1 year ago

According to https://github.com/dotnet-foundation/website/issues/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 https://github.com/dotnet/docfx/issues/4250 and https://github.com/dotnet/docfx/issues/7663. The schema library was replaced in v2.63.0 https://github.com/dotnet/docfx/pull/8418 but AFAICT the iTextSharp dependency is still there and is shipped in the docfx tool package.

ChrisSfanos commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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!