search

TEIC / Stylesheets

TEI XSL Stylesheets
231 stars 124 forks source link

need to document update p5subset procedure #500

Closed sydb closed 9 months ago

sydb commented 3 years ago

We have agreed that p5subset should periodically be copied into Stylesheets/source/. We should document that process so that questions like

etc. are easily answered.

martindholmes commented 3 years ago

I think @sydb and I agree that the best source for p5subset.xml is the latest build output of TEIP5-dev on the main Jenkins machine.

On tests, I see no reason why they shouldn't all be run and fixed. At the moment, Test2 is not really official so it would be fine to leave fixing Test2 problems to @sydb and me, but since the Jenkins jobs will also run the full suite of tests, it makes sense to run and fix locally before pushing changes to the repo.

martindholmes commented 3 years ago

This is actually easy to document, but the question is where does that documentation belong? Anybody? A new TCW?

sydb commented 2 years ago

We (Stylesheets group) are not sure where this documentation should end up — it depends a lot on for how long we need to do this manually, eh @peterstadler? — but we have started scratching out some initial information on a GoogleDoc (available to Council only while it is a GoogleDoc, will be public once moved to wiki or TCW or whatever).

martinascholger commented 2 years ago

@sydb, @martindholmes, @JanelleJenstad could you please review and expand the notes in the google doc -- Thanks!

JanelleJenstad commented 2 years ago

I've read it over and have a question about intended audience. If the audience is someone like me (new to Council and newish to this kind of work), then it will need much more detail. If the audience is someone more tech savvy, then @sydb and @martindholmes's expansions will suffice. I've run through the update process twice now (once with Syd, I think, and once with Helena).

martindholmes commented 2 years ago

@JanelleJenstad I think the procedure is sufficiently complex that no brand-new Council member is going to attempt it; for one thing, you need to be set up and able to run the tests, and you need to be able to interpret the results and act on them; that means having a fairly sophisticated understanding of P5, the Stylesheets, and how they interact.

sydb commented 2 years ago

Furthermore, there is a good chance we will not have to be doing this for long (i.e., @peterstadler may have a more automated procedure within the next few months). So no point in trying to make this a tutorial in, e.g., setting up a local build.

JanelleJenstad commented 2 years ago

Thanks for the clarification. How about I give the document a good proofreading when you are done? I did leave a note that the document would benefit from a rationale/purpose at the top.

martindholmes commented 10 months ago

@peterstadler Where are we on this? Does it still need to be done, or is there an automated procedure already?

sydb commented 10 months ago

There is no automated procedure. The process is (perhaps poorly) documented in a Google Doc.