Change Details

In order to complete T206163, the Block class needs to be refactored so that blocks made from multiple blocks can be separated out from single blocks. In doing this, we will create an AbstractBlock parent class which can be extended by Block (single blocks) and a new MultipleBlock class. The MultipleBlock class is convenient, because it allows the rest of the codebase (except the BlockManager) to be unaware of overlapping blocks. While we are doing this, it makes sense also to separate out system blocks, which are temporary blocks created against IP addresses listed in global configs. These are never saved to the database. In summary, Block will be refactored into the following classes: `AbstractBlock` - abstract parent class `Block` - blocks that are saved to the database `SystemBlock` - temporary blocks `MultipleBlock` - blocks made from several blocks **Breaking changes** This naming scheme breaks typehints for Block which now could be a SystemBlock or a MultipleBlock. These need to be updated to AbstractBlock. **Naming** There have been some discussions about an alternative naming scheme, in which the parent class is named `Block` and the class for database blocks is called `DatabaseBlock`. This avoids the break mentioned above, but would break calls to static methods such as `Block::newFrom*` and calls to the constructor `new Block()`. Given the prevalence of these across extensions, this would be a much less convenient change. **Plan** 1. Introduce an empty `AbstractBlock` class, and have `Block` extend it. This is just to avoid the breaking change mentioned above and will be quickly followed-up with the refactoring patch. 2. Update any typehints in extensions that use `Block` (but may expect a `SystemBlock` or `MultipleBlock`), based on: https://codesearch.wmflabs.org/deployed/?q=(%3F%3A%5CsBlock%5Cs%7Cinstanceof%5CsBlock)&i=nope&files=&repos= (NB most of these examples are in fact expecting a database `Block`, so do not need to be updated.) 3. Split `Block` into `AbstractBlock`, `Block` and `SystemBlock` 4. Introduce `MultipleBlock` 5. Make `Block` a deprecated alias of `DatabaseBlock`, which is more descriptive

In order to complete T206163, the Block class needs to be refactored so that blocks made from multiple blocks can be separated out from single blocks. In doing this, we will create an AbstractBlock parent class which can be extended by Block (single blocks) and a new MultipleBlock class. The MultipleBlock class is convenient, because it allows the rest of the codebase (except the BlockManager) to be unaware of overlapping blocks. While we are doing this, it makes sense also to separate out system blocks, which are temporary blocks created against IP addresses listed in global configs. These are never saved to the database. In summary, Block will be refactored into the following classes: `AbstractBlock` - abstract parent class `Block` - blocks that are saved to the database `SystemBlock` - temporary blocks `MultipleBlock` - blocks made from several blocks **Breaking changes** This naming scheme breaks typehints for Block which now could be a SystemBlock or a MultipleBlock. These need to be updated to AbstractBlock. **Naming** There have been some discussions about an alternative naming scheme, in which the parent class is named `Block` and the class for database blocks is called `DatabaseBlock`. This avoids the break mentioned above, but would break calls to static methods such as `Block::newFrom*` and calls to the constructor `new Block()`. Given the prevalence of these across extensions, this would be a much less convenient change. **Plan** [x] Introduce an empty `AbstractBlock` class, and have `Block` extend it. This is just to avoid the breaking change mentioned above and will be quickly followed-up with the refactoring patch. [x] Update any typehints in extensions that use `Block` (but may expect a `SystemBlock` or `MultipleBlock`), based on: https://codesearch.wmflabs.org/deployed/?q=(%3F%3A%5CsBlock%5Cs%7Cinstanceof%5CsBlock)&i=nope&files=&repos= (NB most of these examples are in fact expecting a database `Block`, so do not need to be updated.) [] Split `Block` into `AbstractBlock`, `Block` and `SystemBlock` [] Introduce `MultipleBlock` [] Make `Block` a deprecated alias of `DatabaseBlock`, which is more descriptive [] Communicate and verify documentation of the soft deprecation

In order to complete T206163, the Block class needs to be refactored so that blocks made from multiple blocks can be separated out from single blocks. In doing this, we will create an AbstractBlock parent class which can be extended by Block (single blocks) and a new MultipleBlock class. The MultipleBlock class is convenient, because it allows the rest of the codebase (except the BlockManager) to be unaware of overlapping blocks. While we are doing this, it makes sense also to separate out system blocks, which are temporary blocks created against IP addresses listed in global configs. These are never saved to the database. In summary, Block will be refactored into the following classes: `AbstractBlock` - abstract parent class `Block` - blocks that are saved to the database `SystemBlock` - temporary blocks `MultipleBlock` - blocks made from several blocks **Breaking changes** This naming scheme breaks typehints for Block which now could be a SystemBlock or a MultipleBlock. These need to be updated to AbstractBlock. **Naming** There have been some discussions about an alternative naming scheme, in which the parent class is named `Block` and the class for database blocks is called `DatabaseBlock`. This avoids the break mentioned above, but would break calls to static methods such as `Block::newFrom*` and calls to the constructor `new Block()`. Given the prevalence of these across extensions, this would be a much less convenient change. **Plan** 1.[x] Introduce an empty `AbstractBlock` class, and have `Block` extend it. This is just to avoid the breaking change mentioned above and will be quickly followed-up with the refactoring patch. 2.[x] Update any typehints in extensions that use `Block` (but may expect a `SystemBlock` or `MultipleBlock`), based on: https://codesearch.wmflabs.org/deployed/?q=(%3F%3A%5CsBlock%5Cs%7Cinstanceof%5CsBlock)&i=nope&files=&repos= (NB most of these examples are in fact expecting a database `Block`, so do not need to be updated.) 3.[] Split `Block` into `AbstractBlock`, `Block` and `SystemBlock` 4.[] Introduce `MultipleBlock` 5.[] Make `Block` a deprecated alias of `DatabaseBlock`, Make `Block` a deprecated alias of `DatabaseBlock`, which is more descriptivewhich is more descriptive [] Communicate and verify documentation of the soft deprecation