-
-
Notifications
You must be signed in to change notification settings - Fork 33
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
Adopt community XQuery file extension convention #102
Adopt community XQuery file extension convention #102
Conversation
- main modules: .xq - library modules: .xqm
For the motivation, I'll quote from my post at https://gitlab.existsolutions.com/tei-publisher/tei-publisher-app/-/issues/152#note_8478:
And in a followup post in the same thread:
Since that thread 2-3 years ago, the XQuery for Humanists book came out - adding its endorsement of the Thus, for pedagogical and practical purposes, adopting this convention consistently will help both new and longstanding contributors to TEI Publisher and other eXist-based projects instantly understand the nature of each XQuery module in this project by glancing at the file extension. As an example of one such user, I constantly find myself guessing whether an .xql file is a library module or main module and find it frustrating that I have to manually examine the file to know for sure. This PR already updates the documentation where relevant, and I would be happy to contribute to the "updating" article in the documentation for the release where this is included - conceivably, the forthcoming TEI Publisher 8 release. I imagine that the lib and components repos might also need major releases. But this move puts all of the projects on an even more solid foundation, so I would argue that it is worthy of inclusion in a major release. Comments welcome! |
Hi @joewiz, while agreeing in principle re naming conventions, after some discussions we determined that disturbance to existing Publisher editions and potential for confusion for users is too great to justify the change. Therefore I will close this PR, nevertheless many thanks for your work and consideration that went into this proposal. |
@tuurma Thanks for your consideration of the PR. While I agree the proposed shift would have been painful for current users migrating to a new version, the pain would have been limited to one upgrade cycle, and it would have relieved confusion and made it easier for new and existing users to understand the project and contribute to it. The continued inconsistent use of file extensions (not to mention mismatches between module base names, namespace prefixes, and namespace URIs) will continue to impose its own pain - a type of technical debt. I'm sure you've considered this in the calculus, and I fully accept the decision; I thought it worth articulating the trade-off one more time. There may come a day when reworking the naming is worth it. Also, it might be worth adopting a consistent naming convention for new code. A statement to the effect of, say:
|
@joewiz I agree that we may want to rework the naming at some point, perhaps already for the 9 release if, as it seems to me now, it may include further breaking changes. Meanwhile, would you rather keep this PR opened or, as I would actually prefer, open an issue about the conventions you mention, i.e. not only module extensions but also prefixes and URIs? |
@tuurma I like your idea to open a new issue. I'll aim to do so ASAP. |
Requires eeditiones/tei-publisher-lib#7 and eeditiones/tei-publisher-components#92.