[libre-riscv-dev] Introduction

[Jacob Lifshay]

I think we should have a commit size exception for refactoring, since, for
example, if a commonly used function is renamed, you would have to change
every use to match. The refactor commits should be conceptually simple, so
no changing several unrelated things in a single commit.

Jacob

On Sat, Feb 2, 2019, 21:34 Luke Kenneth Casson Leighton <lkcl at lkcl.net
wrote:

> Notes for dev
>
> * nmigen is python, therefore use pep8. Install autopep8 and use -v  -a -a
> -a --experimental. goes in Makefile
> * epydoc (old but still relevant) to be used to extract docstrings. again
> goes in Makefile
> * unit tests (python setup.py test) always to be developed extensively
> (synergistically) at time of code writing, NOT as an afterthought.
> * do not use import * !
> * modules to be kept very small, such that "yosys show" on reading verilog
> produces a small, legible diagram
> * module header to actually explain what the module does. link to
> requirements spec, and any other useful stuff.
> * ascii art recommended in module header to illustrate where bits go.
> * class header likewise required and explain purpose of the class.
> * code comments to be useful but not excessive to the point of drowning the
> code
> * functions not to exceed 60-70 (or so) lines, if possible. if too big,
> split into multiple functions (remember, nmigen constructs can be returned
> from a function)
>
> Git commits
>
> * commits to be SMALL (5 - 15 lines max) and MUST not disrupt existing unit
> tests. unit tests always to be run prior to commit.
> * commits MUST be SINGLE PURPOSE. clue (red flag) is if the commit message
> includes the word "and".
> * commit message to explain purpose (ie not be "changed this" or "added
> that")
> * large commits ok as long as they are additions rather than modifications.
> * whitespace to be separate, "autopep8 cleanup" is sufficient.
> * when using bugtracker, include link to bugreport in commit message. Cross
> ref commit id to bugreport.
>
> That's most things, looks a lot, it really isn't.  General idea behind all
> of these is to make code readable and understandable to others, including
> ourselves!
>
> L.
>
>
> --
> ---
> crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
> _______________________________________________
> libre-riscv-dev mailing list
> libre-riscv-dev at lists.libre-riscv.org
> http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev
>