Update README.md to add intentions and revision policy (gbdev#30)

Co-authored-by: Eievui <[email protected]>
Co-authored-by: Eldred Habert <[email protected]>
Co-authored-by: Antonio Vivace <[email protected]>

README.md

@@ -1,18 +1,28 @@
 # `hardware.inc`
 ### Gameboy Hardware definitions
-`hardware.inc` has been the standard include file containing Game Boy hardware definitions for use in [rgbds](https://github.com/gbdev/rgbds) projects for over 20 years.
+`hardware.inc` has been the standard include file containing Game Boy hardware definitions for use in [RGBDS](https://rgbds.gbdev.io) projects for over 20 years.
 
 The file was originally created by Jeff Frohwein in 1997, who still hosts [his latest version (2.3)](http://www.devrs.com/gb/files/hardware.zip) on his great [Dev'rs](http://devrs.com) website.
 
 Although Jeff tried to version control the file with a rudimentary change log at the top of the file, people have added small changes throughout the years, often without bumping the version number.
 
-This repo is an attempt at version control, using [@AntonioND](http://github.com/AntonioND) fork as baseline.
+This repo has become the new official reference for `hardware.inc`, using [@AntonioND](http://github.com/AntonioND)'s fork as the baseline.
+
+## Contributing
+
+This repository's `master` branch should be considered production;
+Each commit represents a new release, requiring the embedded version number to be bumped (and an entry to be added to the changelog at the beginning of the file).
+
+We follow [semantic versioning](https://semver.org);
+Breaking changes (such as those in [72ec03f](https://github.com/gbdev/hardware.inc/commit/72ec03f835e72be83a1ef189a4a9eac0fbdf39e2)) increase the major version, backwards-compatible changes (typically additions) only increase the minor version, and bugfixes only increase the patch level.
+
+Changes to the comments should be considered a bugfix.
 
 ## Contributors
 
 * Jones (created the original `hardware.inc`, now lost)
 * Carsten Sørensen (whose ideas Jeff based his file on)
 * Jeff Frohwein
 * AntonioND
-* BlitterObjectBob, tobiasvl, ISSOtm,  avivace, GreenAndEievui, QuinnPainter, rondnelson99, daid, Hacktix, sukus21, alvaro-cuesta, basxto
+* BlitterObjectBob, tobiasvl, ISSOtm, avivace, Eievui, QuinnPainter, rondnelson99, daid, Hacktix, sukus21, alvaro-cuesta, basxto
 * Probably lots of other people who have added to the file throughout the years

hardware.inc

@@ -33,6 +33,9 @@
 ;* Rev 4.5 - 03-Mar-22 : Added bit number definitions for OCPS, BCPS and LCDC (sukus)
 ;* Rev 4.6 - 15-Jun-22 : Added MBC3 registers and special values
 
+; NOTE: REVISION NUMBER CHANGES MUST BE REFLECTED
+; IN `rev_Check_hardware_inc` BELOW!
+
 IF __RGBDS_MAJOR__ == 0 && __RGBDS_MINOR__ < 5
     FAIL "This version of 'hardware.inc' requires RGBDS version 0.5.0 or later."
 ENDC
@@ -42,12 +45,21 @@ ENDC
     IF !DEF(HARDWARE_INC)
 DEF HARDWARE_INC EQU 1
 
+; Usage: rev_Check_hardware_inc <min_ver>
+; Examples: rev_Check_hardware_inc 4.1.2
+;           rev_Check_hardware_inc 4.1 (equivalent to 4.1.0)
+;           rev_Check_hardware_inc 4 (equivalent to 4.0.0)
 MACRO rev_Check_hardware_inc
-;NOTE: REVISION NUMBER CHANGES MUST BE ADDED
-;TO SECOND PARAMETER IN FOLLOWING LINE.
-    IF  \1 > 4.6 ;PUT REVISION NUMBER HERE
-        WARN    "Version \1 or later of 'hardware.inc' is required."
+    DEF CUR_VER equs "4,6,0"    ; ** UPDATE THIS LINE WHEN CHANGING THE REVISION NUMBER **
+    DEF MIN_VER equs STRRPL("\1", ".", ",")
+    DEF INTERNAL_CHK equs """MACRO ___internal
+    IF \\1 != \\4 || \\2 < \\5 || (\\2 == \\5 && \\3 < \\6)
+    	FAIL "Version \\1.\\2.\\3 of 'hardware.inc' is incompatible with requested version \\4.\\5.\\6"
     ENDC
+\nENDM"""
+    INTERNAL_CHK
+    ___internal {CUR_VER}, {MIN_VER},0,0
+    PURGE CUR_VER, MIN_VER, INTERNAL_CHK, ___internal
 ENDM