The review of SSWG-0032: Hummingbird begins now and runs for two weeks, until April 6th, 2024.
Reviews are an important part of the Swift Server Work Group incubation process. All review feedback should be either on this forum thread or, if you would like to keep your feedback private, directly to the review manager (via email) or direct message in the Swift forums.
The package is being proposed at the Sandbox maturity level. Please note the Maturity Justification inside the proposal for details and indicate which you find more appropriate as part of your review.
What goes into a review of a proposal?
The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, become listed on the Swift Server Ecosystem index page .
When reviewing a proposal, here are some questions to consider:
What is your evaluation of the proposal and its APIs/implementation?
Is the problem being addressed relevant for the wider Swift on Server ecosystem?
Does this proposal fit well with the feel and direction of the Swift Server ecosystem?
If you have used other libraries in Swift or other languages, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
i’d like to offer some feedback about the layout of the project because it presents some challenges for generating and mirroring documentation on places like Swiftinit or Swift Package Index.
right now, the project has an unusual topology which has a single source (the basic Hummingbird repo), lots of intermediate nodes, and a single “sink”, which is the hummingbird-docs repository. i assume this is motivated by the fractured layout of the project and the desire to write documentation that references symbols that live in multiple constituent repos of the project.
this is a perfectly reasonable use case, and something Swiftinit is explicitly designed to support. however, there are things in the hummingbird-docs repository that plainly don’t belong there and should really be upstreamed to the appropriate repository. for example, topics curations, which are intrinsic to the symbol receiving curations and cannot be provided as a documentation extension by an external package.
the articles are fine to continue living in the hummingbird-docs repo, but they are currently in a non-standard directory and need special scripting for docs discovery to work.
my suggestions:
move the topics curations (anything with an h1 heading that points to a symbol, such as # ``HummingbirdCompression`` ) to their native module, which would also be good for maintainability. the curations could still use cross-package linking against the packages their home package depends on (e.g. - ``Hummingbird`` ), they just won’t be able to use cross-package linking against all of the packages the hummingbird-docs repo depends on.
move the articles to the hummingbird_docs anchor module, which will allow them to be discovered while still benefiting from cross-package linking against all of the hummingbird packages.
One of the main goals when setting up the Hummingbird documentation was to have links between documentation from different packages. For example this page in the hummingbird-auth documentation has a link back to documentation for RequestContext in hummingbird. At the time the only way to do this was to centralise the documentation in one repository hummingbird-docs and build it as one bundle.
The hummingbird-docs project is dependent on all other hummingbird projects. I have a custom script that builds this and then extracts all the relevant symbol graph files from the .build folder and then builds a bundle used the documentation in hummingbird-docs and the extracted symbol graph files.
I haven't been following the docc project too closely so perhaps there is a better way to do this now, but maybe this thread isn't the best place to discuss this. If you want to add an issue to the hummingbird-docs repo we can look at alternatives there.
Regarding the Swift Package Index I use a .spi.yml in each project to link to the correct documentation. I'm not sure what the solution would be for swiftinit.
