Finalise guide for working on the file format
Closed this issue · 12 comments
Notes from Notion:
- Goal is to communicate clearly that it's not us dictating changes on the file format but this is the place for everyone making changes on the file persistence layer to define and document them.
- Is it possible to provide a sample scenarios for (non-)breaking change?
- Make clear this is going first and foremost about helping robust products across our organisation
@christianklotz Updates to the guide here - see what you think
I made a few small changes, requires one clarification on what is considered breaking. Looking good otherwise
Once done let's share with Mike, Gavin and Alan initially for feedback before announcing it properly.
I'm happy to open up the discussion on this a little /cc @mikeabdullah @acf @opsGavin
I think it's worth exploring a little more what the actual process might be for keeping everyone aware of changes. Might be worth making some CODEOWNER action of the CoreData model etc in the short term so nobody makes changes without it being known.
@acf sounds good, who would be the best to take on code ownership?
Actually, rather than a CODEOWNER who has to do reviews, I wonder if there might be some way @InvisiblePixels can think of that the mergebot could watch for specific files or patterns and notify people in the merges slack room. I could see it doing things like alerting manga to changes in xibs and any number of people about changes to the coredatamodel 🤔
Its less that a change needs reviewed by someone in particular and more that it needs to be broadcast widely, maybe.
Could it be a GitHub Action that checks for commit changes and then pings a GitHub team? At the time of merge it feels a bit too late to discuss changes on the file format (or .xib files), no?
Could be. I suppose I don't want it necessarily to block commits, but make everyone aware.... but maybe in the file format change we do need to block commits until everyone is aware 🤔
Fundamentally, from my point of view as the person likely to be updating the file format based on changes happening Sketch-side, I just need a heads up like "Hey next Sketch is going to transition to document version 122 and here's how it's changing"
Maybe a ping from a GitHub Action could be good. Or a Danger rule type thing that drops a message in a PR GitHub thread:
I notice you're changing files related to how Sketch documents serialise to JSON. Please raise an issue on the file format repo to discuss any necessary changes to the public schemas.
Actually, rather than a CODEOWNER who has to do reviews, I wonder if there might be some way @InvisiblePixels can think of that the mergebot could watch for specific files or patterns and notify people in the merges slack room. I could see it doing things like alerting manga to changes in xibs and any number of people about changes to the coredatamodel 🤔
That's implementable. Whether it's mergebot that checks or the integration job, it's all configurable. Just need to know what you want looking out for and what to do when I find it.
Suspect mergebot might be a bit late though? If you want to flag changes for discussion.
Closing for now, we see how things go with the next few changes being introduced to the file format and revisit if necessary.