Skip to content

Instantly share code, notes, and snippets.

@qexat

qexat/the_bug_fix_workflow.txt

Last active August 27, 2025 15:21
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save qexat/a1b447718c6a71b846de3400e70edbc3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save qexat/a1b447718c6a71b846de3400e70edbc3 to your computer and use it in GitHub Desktop.
Download ZIP
the bug fix workflow, using ribbon's project version control system
Raw
the_bug_fix_workflow.txt
%%%%%%%%%%%%%%%%%%%%%%%%
% the bug fix workflow %
%%%%%%%%%%%%%%%%%%%%%%%%
=========================
what does a bug fix have?
=========================
-> a name that can be referenced
-> a description to use in commit & release
-> a set of witness tests that check whether the fix is working
----
name
----
a simple identifier to be shown in UIs, or used to reference that
specific bug fix (for example, if you want to come back to it).
similar to a git hash but more user-friendly.
-----------
description
-----------
a short summary of /what/ the fix is about (not how it is done!).
it is set /before/ doing the actual fix, so you have a sort of
contract that forces you to stay in scope!
-------------
witness tests
-------------
a selection of tests that demonstrate whether the fix is effective.
they can be a failing test that should pass, or a passing test that
should be failing. tests are referenced by an identifier, which is
what you give to the tool.
note: tests not marked as witnesses are still checked. they have to
remain unaffected by the fix, including currently failing ones!
=================
cooking a bug fix
=================
1. set up a bug fix
2. write the bug fix
3. run the checks
4. if needed, go back to 2 or 3
----------------
set up a bug fix
----------------
as simple as:
ribbon fix new [name] [description] [...test identifiers]
if one of those is missing, an interactive TUI will prompt you.
you might prefer using it if you want to write new tests that will be
witnesses.
-----------------
write the bug fix
-----------------
it is the part where you modify your project source code to fix that
bug. make sure to stay in scope of the fix!
--------------
run the checks
--------------
once you think you are done, run the following:
ribbon fix check
it will run the witness tests to check if they are correctly
affected, run the other tests to make sure those are not, and perform
other hooks such as linting or formatting to make sure the changed
code is still compliant.
note: it also runs all the tests at once to detect potential test
pollution.
==============================
the fix did not pass checking!
==============================
there are a few cases where this could happen:
-> the changes you made did not actually fully fix the bug
-> the fix has affected other parts of the code
-> you forgot to mark some tests as witnesses
-------------------
bug not fully fixed
-------------------
review your fix and figure out what is still not working.
------------------------
unrelated tests affected
------------------------
this can be a symptom of two things: either your fix has a leaking
scope (it is doing more than fixing the bug), or there is what is
called /test pollution/ in your test suite. the latter is often
caused by tests relying on a global state in improper ways. make sure
your tests are as independent as possible, especially between witness
and non-witness ones.
---------------------------------------
tests correctly affected but not marked
---------------------------------------
if you have tests affected as expected, you can mark them as
witnesses:
ribbon fix witness mark <...test identifiers>
do /not/ mark tests as witnesses if they are not related to the bug
fix! this is /not/ an escape hatch, you will end up with a release
that has unfixed issues!
=====================
the checks are green!
=====================
great! it is time for a patch release:
ribbon fix release
it will handle committing your fix, preparing for a new release
(including incrementing the version for you!) and requesting the
the package index.
if you are using git as the backend, it will create a new tag.
if your repository host supports that, it will also publish a new
release there.
==========================
useful additional commands
==========================
-------------
quick release
-------------
the following command:
ribbon fix done
combines checking and releasing at once.
useful for one-shots!
---------------------------------
need to work on something else...
---------------------------------
if fixing the bug is harder than expected and/or you need to work on
something more important, you can put the bug fix aside:
ribbon fix stash
when it will be time, you can come back to it:
ribbon fix resume <name>
-----------------------------
spotted something to do later
-----------------------------
while working on a bug fix, you might notice some unrelated code that
you want to change later. you can tell ribbon about it:
ribbon remember <type> <description> [...files, functions, spans]
the type is one of the workflows (fix, feature, doc, typo, test...).
it will be reminded to you after the bug fix passes checks and gets
released.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
the project version control system that provides these workflows is
part of the ribbon language's toolchain.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment