On Wed, Jan 03, 2018 at 09:36:30AM -0800, g...@sourceauditor.com wrote: > At some point, these issues will likely turn into a pull request > created by someone quite familiar with the current license XML > format. There currently isn't much documentation on the specifics > for the pull request process itself. > … > The document would be technical in nature and provide guidance on > creating new license XML files…
I think you're going both ways for “these contributors are familiar with the current license XML format”. But regardless of how familiar folks are, documenting that format is good for onboarding new contributors and keeping existing contributors on the same page. I've just finished the initial work on [1], which adds documentation for the schema semantics to our XSD file. I think that's the best place for those docs, because it makes it easier to keep them up to date as the schema evolves. > … process for reviewing and accepting pull requests, use of tags… These sound like maintainer docs. Other projects I'm involved with have a separate MAINTAINERS_GUIDE.md [2] or similar for this sort of thing. > … best practices for license matching markup, limitations in the > current tools, pointers to the XML schemas… This sounds like useful information for anyone reading the XML. I'd rather document the best-practices and tool limitations in the XSD, along side the semantics. That gives XML authors and readers a single place to look to understand a given element or attribute. > … tips on debugging license match failures… This sounds like useful information for both XML authors and matching consumers. But I'm not clear on what sort of content you'd include. This seems more like “we should update the tooling to provide better diagnostics for failed matches”. > … and anything else we can think of that would help technical > contributors to the repository. I'm certainly in favor of improving our documentation, as long as we don't add more documentation than we are able to maintain. Cheers, Trevor [1]: https://github.com/spdx/license-list-XML/pull/586 [2]: https://github.com/opencontainers/project-template/blob/8e4c7e3dbea403c727d7fc526b8dcd53d6c98202/MAINTAINERS_GUIDE.md -- This email may be signed or encrypted with GnuPG (http://www.gnupg.org). For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Spdx-legal mailing list Spdx-legal@lists.spdx.org https://lists.spdx.org/mailman/listinfo/spdx-legal
