the link. Which should not require any kind of login to access. ask the
listadmin if you don't have anywhere suitable: FTP access can be arranged.
+### Actionable items from mailing list
+
If discussions result in any actionable items, it is important not to
lose track of them. Create a bugreport, find the discussion in the
archives <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/>,
involves running an automated perl script from email, on every email,
on the server, that is a high security risk, and i'm not doing it. sorry.)
+### Mailing list != editable document store
+
Also, please do not use the mailing list as an "information or document
store or poor-man's editor". We have the wiki for that. Edit a page and
tell people what you did (summarise rather than drop the entire contents
as an effective organisation. It's *not* about "setting rules and meting
out punishment".
-for actual code development:
+## Coding
+
+for actual code development
+
+### Plan unit tests
* plan in advance to write not just code but a full test suite for
that code. **this is not optional**. large python projects that do not
have unit tests **FAIL** (see separate section below).
+
+### Commit tested or zero-dependent code
+
* only commit code that has been tested (or is presently unused). other
people will be depending on you, so do take care not to screw up.
not least because, as it says in the [[charter]] it will be your
responsibility to fix. that said, do not feel intimidated: ask for help
and advice, and you'll get it straight away.
+
+### Commit often
+
* commit often. several times a day, and "git push" it. this is
collaboration. if something is left even overnight uncommitted and not
pushed so that other people can see it, it is a red flag. if you find
it is making yourself a bottleneck. pair-programming is supposed to help
avoid this kind of thing however pair-programming is difficult to organise
for remote collaborative libre projects (suggestions welcomed here)
+
+### Absolutely no auto-generated output
+
* **do not commit autogenerated output**. write a shell script and commit
that, or add a Makefile to run the command that generates the output, but
**do not** add the actual output of **any** command to the repository.
ever. this is really important. even if it is a human-readable file
rather than a binary object file.
it is very common to add pdfs (the result of running latex2pdf) or configure.in (the result of running automake), they are an absolute nuisance and interfere hugely with git diffs, as well as waste hard disk space *and* network bandwidth. don't do it.
+
+### Write commands that do tasks and commit those
+
* if the command needed to create any given autogenerated output is not
currently in the list of known project dependencies, first consult on
the list if it is okay to make that command become a hard dependency of
the repository and document them at the very minimum in the README,
INSTALL.txt or somewhere in a docs folder as appropriate. if unsure,
ask on the mailing list for advice.
+
+### Keep commits single-purpose
+
* edit files making minimal *single purpose* modifications (even if
it involves multiple files. Good extreme example: globally changing
a function name across an entire codebase is one purpose, one commit,
yet hundreds of files. miss out one of those files, requiring multiple
commits, and it actually becomes a nuisance).
+
+### Run unit tests prior to commits
+
* prior to committing make sure that relevant unit tests pass, or that
the change is a zero-impact addition (no unit tests fail at the minimum)
+
+### Do not break existing code
+
* keep working code working **at all times**. find ways to ensure that this is the case. examples include writing alternative classes that replace existing functionality and adding runtime optiobs to select between old and new code.
+
+### Small commits with relevant commit message
+
* commit no more than around 5 to 10 lines at a time, with a CLEAR message
(no "added this" or "changed that").
* if as you write you find that the commit message involves a *list* of
changes or the word "and", then STOP. do not proceed: it is a "red flag"
that the commit has not been properly broken down into separate-purpose
commits. ask for advice on-list on how to proceed.
+
+### Exceptions to small commit: atomic single purpose commit
+
* if it is essential to commit large amounts of code, ensure that it
is **not** in use **anywhere** by any other code. then make a *small*
(single purpose) followup commit which actually puts that code into use.
change which integrates untested code: just commit the new code (only)
and follow up the next day *after* running the full relevant unit tests.
+### Why such strict rules?
+
the reason for all the above is because python is a weakly typed language.
make one tiny change at the base level of the class hierarchy and the
effect may be disastrous.
commit confuses several unrelated changes, not only the diff is larger
than it should be, the reversion process becomes extremely painful.
+### PEP8 format
+
* all code needs to conform to pep8. use either pep8checker or better
run autopep8. however whenever committing whitespace changes, *make a
separate commit* with a commit message "whitespace" or "autopep8 cleanup".
you think you need greater than 80 chars, it *fundamentally* indicates
poor code design. split the code down further into smaller classes
and functions.
+
+### Docstring checker
+
* TBD there is a docstring checker. at the minimum make sure to have
an SPD license header, module header docstring, class docstring and
function docstrings on at least non-obvious functions.
+
+### Clear code commenting and docstrings
+
* make liberal but not excessive use of comments. describe a group of
lines of code, with terse but useful comments describing the purpose,
documenting any side-effects, and anything that could trip you or other
developers up. unusual coding techniques should *definitely* contain
a warning.
+
+### Only one class per module (ish)
+
* unless they are very closely related, only have one module (one class)
per file. a file only 25 lines long including imports and docstrings
is perfectly fine however don't force yourself. again, if unsure,
ask on-list.
+
+### File and Directory hierarchy
+
* *keep files short and simple*. see below as to why
* create a decent directory hierarchy but do not go mad. ask for advice
if unsure
+
+### No import star!
+
* please do not use "from module import \*". it is extremely bad practice,
causes unnecessary resource utilisation, makes code readability and
tracking extremely difficult, and results in unintended side-effects.
+
+### Keep file and variables short but clear
+
* try to keep both filenames and variable names short but not ridiculously
obtuse. an interesting compromise on imports is "from ridiculousfilename
import longsillyname as lsn", and to assign variables as well: "comb =
m.d.comb" followed by multiple "comb += nmigen_stmt" lines is a good trick
that can reduce code indentation by 6 characters without reducing clarity.
+### Reasons for code structure
+
regarding code structure: we decided to go with small modules that are
both easy to analyse, as well as fit onto a single page and be readable
when displayed as a visual graph on a full UHD monitor. this is done
projects / libreriscv.git / commitdiff