proprietary nonfree service "because it's soooo convenient", as the
lions are getting wind and gout from overfeeding on that one.
+one.
+
+### Why raise issues
+
+* [Bug #1126](https://bugs.libre-soc.org/show_bug.cgi?id=1126)
+
+If you have discovered a problem in Libre-SOC (software, hardware, etc.),
+please raise a bug report!
+Bug reports allow tracking of issues, both to make the developers lives easier,
+as well as for tracking completed grant-funded work.
+
+It is **extremely** important to link the new bug to previous ones. As Luke
+mentioned on [this bug](https://bugs.libre-soc.org/show_bug.cgi?id=1139#c3),
+"it is a mandatory project requirement that the graph from any bug
+contain all other bugs (one "Group")".
+
+The primary reason for this is to ensure bugs don't get buried and lost,
+and will aid those tackling similar problems at a later time.
+
+Also, for project management and financing purposes, it helps developers
+to keep an up-to-date list of their tasks.
+
+####How to raise issues
+
+1. Create a bug report.
+2. Add in any links from the mailing list or IRC logs to the bug report for back tracking
+ (this is mandatory). Also fill in the URL field if there is a relevant wiki page.
+3. CC in relevant team members
+4. make absolutely sure to fill in "blocks", "depends on" or "see also" so that the
+ bug is not isolated (otherwise bugs are too hard to find if isolated from everything else)
+5. Ping on IRC to say a bug has been created
+6. Unless you know exactly which milestone to use, leave blank initially. This
+also applies when editing milestone, budget parent/child, toml fields. See
+section [[HDL_workflow#Task management guidelines]] further down.
+7. After setting the milestone, it is **absolutely required** to run
+[budget-sync](https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD),
+as it will point out any discrepancies. The budget allocations will be used for
+accounting purposes and **MUST** be correct. *Note you can only get paid for
+stuff done **after the nlnet grant is approved** (before the MOU is signed)*
+
+If a developer ever needs to check which bugs are assigned to them, go to the
+Libre-SOC bug tracker
+[advanced search page](https://bugs.libre-soc.org/query.cgi?format=advanced),
+and in the "Search by People" section, check "Bug Assignee" and "contains"
+and write your nickname (i.e. andrey etc.).
+
## ikiwiki
Runs the main libre-soc.org site (including this page). effective,
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 !$
git clone --recursive https://github.com/billzorn/sfpy.git
cd sfpy
+ git apply /path/to/ieee754fpu/sfpy.patch
cd SoftPosit
git apply ../softposit_sfpy_build.patch
git apply /path/to/ieee754fpu/SoftPosit.patch
* mkdir ~/src
* cd !$
-* git clone gitolite3@git.libre-soc.org:nmigen.git
+* git clone https://gitlab.com/nmigen/nmigen
+* git clone https://gitlab.com/nmigen/nmigen-boards
+* git clone https://gitlab.com/nmigen/nmigen-soc
+* git clone https://gitlab.com/nmigen/nmigen-stdio
* git clone gitolite3@git.libre-soc.org:c4m-jtag.git
* git clone gitolite3@git.libre-soc.org:nmutil.git
* git clone gitolite3@git.libre-soc.org:openpower-isa.git
* git clone gitolite3@git.libre-soc.org:ieee754fpu.git
-* git clone gitolite3@git.libre-soc.org:nmigen-soc.git
* git clone gitolite3@git.libre-soc.org:soc.git
-In each of these directories, **in the order listed***, track down the
+In each of these directories, **in the order listed**, track down the
`setup.py` file, then, as root (`sudo bash`), run the following:
* python3 setup.py develop
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
preferably with a link to a URL in the [bugtracker](https://bugs.libre-soc.org/)
with further details as to why the unit test should not be run.
+# Task management guidelines
+
+1. Create the task in appropriate "Product" section with appropriate
+ "Component" section. Most code tasks generally use "Libre-SOC's
+ first SOC".
+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.
+4. Choose the correct NLnet milestone. The best practice is to check
+ the parent task for a correct milestone.
+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.
+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
Find appropriate tutorials for nmigen and yosys, as well as symbiyosys.