From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Mon, 11 Feb 2019 04:34:11 +0000 (+0000)
Subject: add to dev notes
X-Git-Tag: convert-csv-opcode-to-binary~4737
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f76d89bb76868762dbc6809e21f4eaf3cd5ffb90;p=libreriscv.git

add to dev notes
---

diff --git a/3d_gpu/devnotes.mdwn b/3d_gpu/devnotes.mdwn
index 0814cbdf0..96214deae 100644
--- a/3d_gpu/devnotes.mdwn
+++ b/3d_gpu/devnotes.mdwn
@@ -33,3 +33,33 @@
 * large refactoring (e.g. renaming functions) needs to be atomic and
   single-purpose as best as possible.  unit tests still need to pass,
   post-refactor.
+
+# Which files should be added to the repository
+
+**Only source files must be added to the repository.**
+
+Output that is created from another command must not, with
+very very few exceptions, be added to the repository.  The reason is
+simple: each time a source file is modified, the auto-generated
+(compiled) output **also** changes.  If those changes are added
+to the repository, they become confused with the source code.
+If they are **not** added to the repository, the source and its
+auto-generated output become out-of-sync.
+
+**Either way is bad**.
+
+Instead, the following is advised:
+
+* add the source code *only*
+* add a script or command that builds the source code, generating the output
+* do *NOT* add the *output* to the repository
+* add the script or command to the Makefile
+* list the command as a "build dependency" in the documentation
+
+As a convenience and a courtesy, consider creating "release tarballs"
+(also adding the means to create them to the Makefile) so that people who
+for one reason or another cannot get or install the build dependencies
+may at least get the end-result of the work.  However this should be
+done as a low priority, or if there are financial offers of sponsorhip
+or other incentives received or to be gained by doing so.
+