for actual code development:
+* 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.
* **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.
-* 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 project (hint: java, node.js php and .NET commands may cause delays in response time due to other list participants laughing hysterically), and after a decision is made, document the dependency and how its source code is obtained and built (hence why it has to be discussed)
-* if you find yourself repeating commands regularly, chances are high that someone else will need to run them, too. therefore, put them into a .sh shell script (and/or a Makefile) and document them at the very minimum in README or INSTALL.txt or somewhere in a docs folder as appopriate. if unsure, ask on the mailing list for advice.
-* 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**.
-* 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).
-* prior to committing make sure that relevant unit tests pass, or that the change is a zero-impact addition.
-* commit no more than 5 to 10 lines at a time, with a CLEAR message (no "added this" or "changed that").
+* 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 project (hint: java, node.js php and .NET commands may cause delays in response time due to other list participants laughing hysterically), and after a decision is made, document the dependency and how its source code is obtained and built (hence why it has to be discussed carefully)
+* if you find yourself repeating commands regularly, chances are high that someone else will need to run them, too. clearly this includes yourself, therefore, to make everyone's lives easier including your own, put them into a .sh shell script (and/or a Makefile), commit them to 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.
+* 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).
+* 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).
+* 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)
+* 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.
-* if it is essential to commit large amounts of code, ensure that it is **not** in use **anywhere** by any other code.
+* 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.
-the reason for 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.
+this last rule is kinda flexible, because if you add the code *and* add the unit test *and* added it into the main code *and* ran all relevant unit tests on all cascade-impacted areas by that change, that's perfectly fine too. however if it is the end of a day, and you need to stop and 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.
+
+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.
+
+it is therefore worth reiterating: make absolutely certain that you *only* commit working code or zero-impact code.
therefore, if you are absolutely certain that a new addition (new file, new class, new function) is not going to have any side-effects, committing it (a large amount of code) is perfectly fine.
projects / libreriscv.git / commitdiff