Planned 2.0 Rework
This page is to capture future breaking changes that we would like to make to complete / clean-up non-breaking changes made under 1.x. Rather than clutter the issue tracker with these items that may not be addressed for a very long time, we will capture them here.
This is also a useful guide for developers to see 1.x concepts that may be deprecated, and how to avoid these items.
#401 added an improved method for representing capitalization definitions. We believe conversion_timing is no longer necessary with that representation, and could potentially conflict with it if both are present.
Don't allow converts_to_stock_class_id and converts_to_future_round: true on the same conversion right
Currently the schema allows a stock class ID and converts_to_future_round: true on the same conversion right. This doesn't make sense for a single conversion right; if both things are possible they should be on separate conversion rights. However, adding this requirement now would be a breaking change.
We could add a check to a data validator now, and WARN that this will not be possible in v2.
As discussed in PR #397, we want to refactor our equity structure so that we aren't grouping different types of instruments under top level categories (currently Equity Compensation, Stock, Warrants and Convertiblers). We have a number of things that don't cleanly roll up and we already had to do one super painful refactor to rename Plan Securities to Equity Compensation to fix some nonsensical naming implications (e.g. we faced having Plan Securities not linked to a plan for planless options...). There are other synthetic "equity" types we'll probably want to add ("Phantom Stock" for one), and, no doubt we'll continue to see new types of instruments crop up. Shoe-horning all of these things into four equity types is going to get increasingly tenuous. Another simple and obvious example - most people see RSAs as equity compensation BUT they are structurally identical to stock with vesting and an optional stock plan link and were implemented as a type of Stock.
Long-Term Refactor Proposal for v2.0.0
Where a warrant provides a quantity, we want to add a validation to require a quantity_source. This is currently a breaking change and has not been implemented.
We added an early_exercisable field on our Plan Security Issuances. It's an optional boolean field but ideally should be required and just set it to False rather than omit it if it's not True. This is a breaking change, however, so this was postponed to v2.
We've started to use "$comment" fields in the schemas on properties to mark planned deprecations or breaking changes. A standardized format there plus some tooling to traverse the schema and pull these out would go a long way towards helping with maintenance.