prior to installing any further python-based Libre-SOC HDL repositories.
If "pip3 list" shows that nmigen has been auto-installed please remove it**
-[nmigen](https://nmigen.info/) may be installed as follows:
+[nmigen](https://m-labs.hk/gateware/nmigen/) may be installed as follows:
* mkdir ~/src
* cd !$
commit confuses several unrelated changes, not only the diff is larger
than it should be, the reversion process becomes extremely painful.
+### PHP-style python format-strings
+
+As the name suggests, "PHP-style" is not given as a compliment.
+Format-strings - `f"{variable} {pythoncodefragment}" are a nightmare
+to read. The lesson from PHP, Zope and Plone: when code is embedded,
+the purpose of the formatting - the separation of the format from
+the data to be placed in it - is merged, and consequently become
+unreadable.
+
+By contrast, let us imagine a situation where 12 variables need to
+be inserted into a string, four of which are the same variablename:
+
+ x = "%s %s %s %s %s %s %s %s %s %s %s %s" % (var1, var2, var3,
+ var3, var4, var2,
+ var1, var9, var1,
+ var3, var4, var1)
+
+This is just as unreadable, but for different reasons. Here it *is*
+useful to do this as:
+
+ x = f"{var1} {var2} {var3}" \
+ ...
+ f"{var3} {var4} {var1}"
+
+As a general rule, though, format-specifiers should be strongly
+avoided, given that they mix even variable-names directly inside
+a string.
+
+This additionally gives text editors (and online web syntax
+highlighters) the opportunity to colour syntax-highlight the
+ASCII string (the format) from the variables to be inserted *into*
+that format. gitweb for example (used by this project) cannot
+highlight string-formatted code.
+
+It turns out that colour is processed by the **opposite** hemisphere
+of the brain from written language. Thus, colour-syntax-highlighting
+is not just a "nice-to-have", it's **vital** for easier and faster
+identification of context and an aid to rapid understanding.
+
+Anything that interferes with that - such as python format-strings -
+has to take a back seat, regardless of its perceived benefits.
+
+**If you absolutely must** use python-format-strings, **only** do
+so by restricting to variables. Create temporary variables if you
+have to.
+
+ y = '/'.join(a_list)
+ x = f"{y}"
+
### PEP8 format
* all code needs to conform to pep8. use either pep8checker or better
# Task management guidelines
-* Create the task in appropriate "Product" section with appropriate
+1. Create the task in appropriate "Product" section with appropriate
"Component" section. Most code tasks generally use "Libre-SOC's
first SOC".
-* Fill in "Depends on" and "Blocks" section whenever appropriate.
-* Choose the correct task for a budget allocation. Usually the parent
+2. Fill in "Depends on" and "Blocks" section whenever appropriate.
+ Also add as many related ("See Also") links to other bugreports
+ as possible. bugreports are never isolated.
+3. Choose the correct task for a budget allocation. Usually the parent
task is used.
-* Choose the correct NLnet milestone. The best practice is to check
+4. Choose the correct NLnet milestone. The best practice is to check
the parent task for a correct milestone.
-* Assign the budget to the task in "USER=SUM" form, where "USER"
+5. Assign the budget to the task in `"USER=SUM"` form, where "USER"
corresponds to your username and "SUM" corresponds to the actual
budget in EUR. There may be multiple users.
-* When the task is completed, you can submit an RFP.
-* Once the RFP is sent, notify Luke (lkcl), and update the "USER=SUM"
- field: "USER={amount=SUM, submitted=SDATE}". The SDATE is entered in
- YYYY-MM-DD form.
-* Once the task is paid, update "USER={amount=SUM, submitted=SDATE}"
- to "USER={amount=SUM, submitted=SDATE, paid=PDATE}". The PDATE is
- entered in YYYY-MM-DD form, too.
+6. When the task is completed, you can begin writing an RFP.
+ **DO NOT submit it without explicit authorisation and review**.
+ Leave out your bank and personal address details if you prefer
+ when sending to the Team Manager for review.
+7. Once the RFP is written, notify the Team Manager and obtain their
+ explicit approval to send it.
+8. Once approval is received and the RFP sent, update the `"USER=SUM"`
+ field to include the submitted date:
+ `"USER={amount=SUM, submitted=SDATE}"`. The SDATE is entered in
+ `YYYY-MM-DD` form.
+9. Once the task is paid, again notify the Team Manager (IRC is fine),
+ and update `"USER={amount=SUM, submitted=SDATE}"`
+ to `"USER={amount=SUM, submitted=SDATE, paid=PDATE}"`. The PDATE is
+ entered in `YYYY-MM-DD` form, too.
+
+Throughout all of this you should be using budget-sync to check the
+database consistency
+<https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD>
+
+[[!img bugzilla_RFP_fields.jpg size=640x ]]
# TODO Tutorials