From 6831db7b3ff492cd87262eeee23f5aa2cbd62429 Mon Sep 17 00:00:00 2001 From: lkcl Date: Thu, 13 Feb 2020 23:05:17 +0000 Subject: [PATCH] --- HDL_workflow.mdwn | 61 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn index 8ec8c1683..f7f2ef87f 100644 --- a/HDL_workflow.mdwn +++ b/HDL_workflow.mdwn @@ -65,6 +65,8 @@ minimum look up and understand the following: 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 , @@ -79,6 +81,8 @@ of links into the bugtracker. The bugtracker sends copies of comments 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 @@ -433,16 +437,26 @@ to the [[charter]] because the charter is about ensuring that we operate 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 @@ -451,12 +465,18 @@ for actual code development: 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 @@ -471,20 +491,35 @@ for actual code development: 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. @@ -497,6 +532,8 @@ do not have time to run the necessary unit tests, do *not* commit the 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. @@ -520,6 +557,8 @@ easy-to-find message, it cannot even be located, and once found, if the 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". @@ -527,30 +566,50 @@ than it should be, the reversion process becomes extremely painful. 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 -- 2.30.2