-
Notifications
You must be signed in to change notification settings - Fork 46
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Extensions: Consider normative content about how extensions are published #1571
Comments
Considering all of those options:
My feeling is that it shouldn't be too difficult to word it sufficiently, going for (1) and establishing the assumption as the normative rule but adding the substitution rule as a permissible alternative seems the way to go. |
Sounds good. We already implemented (4) in the profile builder, so the permissible alternative has no additional development cost. Noting that a simpler version of (3) would have been to add support for full URLs. The main downside is the development time to update libraries to handle this scenario (not difficult for us, but not obvious for others). |
Noting that all 3 location links in the initial issue description that contain the extension guidance are currently explicitly named as non-normative pages in https://standard.open-contracting.org/staging/1.2-dev/en/governance/normative/#normative-content.
So we should explicitly declare either https://extensions.open-contracting.org/en/publishers/ or https://github.com/open-contracting/standard_extension_template/blob/master/README.md as normative as this is where the new guidance will be added. My feeling is https://extensions.open-contracting.org/en/publishers/ should be the normative guidance, and the bit added to https://github.com/open-contracting/standard_extension_template/blob/master/README.md can be the non-normative bit with the permissible alternative described? |
@jpmckinney First stab at the wording where in both instances I've put the new words in italics and used Hemingway to try and remove passive voice and sentences it thought were "very hard to read". In https://extensions.open-contracting.org/en/publishers/#document where this will be normative content "You will need to find somewhere to host your extension online at a stable URL. You must publish your extension in a public web-accessible directory (or API that behaves like a directory). Using this kind of location means that the URL path of each file ends in the file name, but is otherwise identical . For example, replacing And in https://github.com/open-contracting/standard_extension_template/blob/master/README.md using non-normative version of the above "† Use of git for version control is recommended, but optional. You need to host your extension on a public HTTP server, with a file structure that matches that in this template repository. You need to publish your extension in a web-accessible directory (or API that behaves like a directory). Using this kind of location means that the URL path of each file ends in the file name, but is otherwise identical . For example, replacing @duncandewhurst feel free to weigh in on wording and location too :) |
Regarding the location of the normative statement, I would put it in https://standard.open-contracting.org/staging/1.2-dev/en/schema/conformance_and_extensions/#extensions. I took a pass at wording the actual rule:
The non-normative documentation can provide guidance on the practical options for conforming to the rule. Rather than documenting the guidance in two places, I would document it in https://extensions.open-contracting.org/en/publishers/#document and then update the note in the extension template to refer to that guidance, e.g. For guidance on how to publish your extensions, refer to... |
@duncandewhurst's proposed wording looks good. The two open issues on the template repo are essentially about eliminating its readme, so we can also pursue that option as part of (or as follow-up to) this issue: https://github.com/open-contracting/standard_extension_template/issues Normative content can be added to https://standard.open-contracting.org/staging/1.2-dev/en/schema/conformance_and_extensions/#extensions as suggested, and it can be repeated at https://extensions.open-contracting.org/en/publishers/#document |
Great thanks both, agree with @duncandewhurst's wording and where to put it. I think it makes sense to partly tackle the template repo issues as part of this, so
|
Actually I now think we're better treating this as two separate issues. So for this issue just:
We can then close this issue and tackle the issue of moving the template README content over to the extension explorer and adding more to the README on what makes a good README |
I agree with your approach! |
I added the template's two issues to the OCDS 1.2 project. |
closing this as remaining issues are detailed in open-contracting/standard_extension_template#41 and open-contracting/standard_extension_template#37 |
We presently assume that extensions are published in a web-accessible directory (or API that behaves like a directory), such that
extension.json
can be trimmed from the end of a URL and replaced with a schema or codelist file.Some publishers publish via APIs (e.g. Visual Studio) where the file path is a query string parameter.
The available documentation on creating extensions is:
Options:
extensions
array would also have to be links to ZIP files.schemas
andcodelists
keys inextension.json
) to be absolute URLs and/or relative URLs.extension.json
in the URL with the desired path should work.Considerations:
The text was updated successfully, but these errors were encountered: