We Have a PCB Now!

Some Thoughts on Version Control Commit Policies

This blog is dedicated to the product making of Z79Forth as a kit, which it makes it primarily a hardware thing. However, in practice, the output of the project is actually 80% software. Today, I committed to Subversion a massive change which I call the "RTC release." This is quite a complex change that includes fixes for mundane things (>IN not being updated systematically as it should be) and major features, like the NMI interrupt handler and optional support for an RTC chip at a reduced CPU clock rate (1/4th of the standard bus frequency).

In a professional context (i.e. in the context of team based development), I did observe that the trend was to commit every small change at the earliest possible opportunity and, possibly through some GitLab enforced policy, have them reviewed by peer developers. Whatever the company policy is, I found that the quality of the reviews before accepting a branch merge was lacking. Usually we are too busy and too small a team to go into in depth code reviews of each other's code. Sometimes we do not even know enough to pass judgement about other team members' production (Windows versus Unix development).

So there you go, so much for "The Surgical Team" approach which "The Mythical Man-Month" praised in the 1975 book by Frederick Brooks. I am not saying that this approach cannot work. All I am saying is it cannot work in the context of the intense pressure for timely deliveries that is put on IT software delivery teams nowadays. I am sure, and I have experienced it firsthand, that it can work and should be the preferred way when doing research work.

 

In a one man project like Z79Forth, which is not driven by commercial imperatives or hard deadlines, attention to quality and detail is privileged. So the commit policy is free (i.e. not dictatorially enforced) and infrequent. A non-regression test framework exists and is run frequently. Extensive code reviews are done before any commit and they are performed by me only (who else would care?).

Quality is expensive and, one way or another, the price for it has to be paid.

Here's the latest commit log for the RTC release:

  doc:
- 79-STANDARD-docreq.txt:
  . update the ACIA oscillator frequency and operating baud rates.
  . recommend the DIV3 path.
  . replaced polling implentation references by interrupt driven ones.
  . also mention software flow control.
  . update the console cooked control primitives (add intr).
  . remove all references to character losses over the FTDI chip.
- 79-STANDARD-subset.txt:
  . outsourcing of DUMP to examples/dump.4th (CompactFlash storage).
  . add descriptions for RTC@ RTC! and TICKS.
- COMPILING.txt:
  . document dictionary contents independance from the feature vector.
  . remove HVFIRQ and VT100.
  . add RTCFEAT (disabled by default).
  . add HVNMI (enabled by default).
  . refocus MSLCNT on a 4 MHz bus clock frequency.
- serbuf.txt:
  . new file (implementation notes).

examples:
- 100fact.4th: new file (contributed by Michel Jean).
- dump.4th: Forth code for what was previously implemented in ROM.
- mandel.4th: new file (contributed by Martin H--GitHub).
- rtc.4th: new file. RTC support code and basic testing.

reference:
- Atmel-0364-PLD-ATF16V8B-8BQ-8BQL-Datasheet.pdf: new candidate GAL
  for extensions.
- CMOS-Cookbook.pdf: new file.
- Panasonic-10000uF.pdf: decoupling capacitor (low ESR).
- TTL-Cookbook.pdf: new file.

src/06_forth:
- console.asm:
  . FIRQHDL: call RTCIHDL is RTCFEAT is enabled.
  . FIRQHDL: set high water mark to 15 (was 32).
  . FIRQHDL: increment SBDROPC (character drop count) when dropping things
    if HVNMI is enabled.
  . GETCH: reduce the degree of competition between base and interrupt level
    code (add some busy waiting at the base level).
- constants.asm:
  . RTCFEAT defaults to 0.
  . HVNMI defaults to 1.
  . map DEV5 to an optional MC146818.
  . add ACIOVRN as a bitmask register content definition.
  . remove DUMP from the users of TBUFF.
- forth.asm:
  . extended credits.
  . additional notes on floored division.
  . feature vector independent dictionary contents (.' MONITOR ICHECK RTC@
    RTC! TICKS).
  . add not about experimental MC146818 RTC support.
  . TICKS and RTCFEAT variables definitions.
  . rebase HDMP4 and HDMP2 on an output buffer pointed to by Y (was X).
  . general HVNMI support.
  . RSTHDL: serial buffer initializations do not need to be performed
    in non-debug mode.
  . _INTERP: >IN fixes (introduce U2INFRD).
  . HEX1D HDMP2 HDMP4 ADDS: output buffer pointed to by Y (was X).
  . add NMIHDL code.
  . get rid of PAG0IN.
  . PRBLKIN: output buffer pointed to by Y.
  . FIND POSTPONE FORGET CHAR [CHAR] WORD (: U2INFRD changes.
  . BYE: wait for 40 milliseconds before rebooting if an RTC was detected.
  . remove DUMP from the dictionary contents.
  . DOTTICK: alternate implementation when SSDFEAT is not enabled.
  . set version to 20220116.
- rtc.asm:
  . RTREGRD no longer clears A.
  . RTREGRD, RTREGWR: only mask FIRQ during operations.
  . RTCINIT: code improvements.
- vlist.txt: updated contents.

util:
- cfinit.sh: add code for DUMP exfiltration to CompactFlash storage.