[PATCH 0/4] Updates to README file

[PATCH 0/4] Updates to README file

[David Gibson]

The README for dtc and libfdt is fairly overdue for an update.
Reformat it in a more modern way, and add some important information
to it.

David Gibson (4):
  Convert README to README.md
  Remove Jon Loeliger from maintainers list
  Split out information for contributors to CONTRIBUTING.md
  Add description of Signed-off-by lines

 CONTRIBUTING.md |  79 ++++++++++++++++++++++++++++++++++++
 README          | 106 ------------------------------------------------
 README.md       | 100 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 179 insertions(+), 106 deletions(-)
 create mode 100644 CONTRIBUTING.md
 delete mode 100644 README
 create mode 100644 README.md

-- 
2.37.1

[PATCH 1/4] Convert README to README.md

[David Gibson]

Let's move vaguely into the twenty-first century by converting our old
plain text README file to Markdown.  While we're updating the formatting,
make some small polish changes to the content.

Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
---
 README    | 106 -----------------------------------------------
 README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 120 insertions(+), 106 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md

diff --git a/README b/README
deleted file mode 100644
index a48312a..0000000
--- a/README
+++ /dev/null
@@ -1,106 +0,0 @@
-The source tree contains the Device Tree Compiler (dtc) toolchain for
-working with device tree source and binary files and also libfdt, a
-utility library for reading and manipulating the binary format.
-
-DTC and LIBFDT are maintained by:
-
-David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
-Jon Loeliger <loeliger-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
-
-
-Python library
---------------
-
-A Python library is also available. To build this you will need to install
-swig and Python development files. On Debian distributions:
-
-   sudo apt-get install swig python3-dev
-
-The library provides an Fdt class which you can use like this:
-
-$ PYTHONPATH=../pylibfdt python3
->>> import libfdt
->>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').read())
->>> node = fdt.path_offset('/subnode@1')
->>> print(node)
-124
->>> prop_offset = fdt.first_property_offset(node)
->>> prop = fdt.get_property_by_offset(prop_offset)
->>> print('%s=%s' % (prop.name, prop.as_str()))
-compatible=subnode1
->>> node2 = fdt.path_offset('/')
->>> print(fdt.getprop(node2, 'compatible').as_str())
-test_tree1
-
-You will find tests in tests/pylibfdt_tests.py showing how to use each
-method. Help is available using the Python help command, e.g.:
-
-    $ cd pylibfdt
-    $ python3 -c "import libfdt; help(libfdt)"
-
-If you add new features, please check code coverage:
-
-    $ sudo apt-get install python3-coverage
-    $ cd tests
-    # It's just 'coverage' on most other distributions
-    $ python3-coverage run pylibfdt_tests.py
-    $ python3-coverage html
-    # Open 'htmlcov/index.html' in your browser
-
-
-The library can be installed with pip from a local source tree:
-
-    pip install . [--user|--prefix=/path/to/install_dir]
-
-Or directly from a remote git repo:
-
-    pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
-
-The install depends on libfdt shared library being installed on the host system
-first. Generally, using --user or --prefix is not necessary and pip will use the
-default location for the Python installation which varies if the user is root or
-not.
-
-You can also install everything via make if you like, but pip is recommended.
-
-To install both libfdt and pylibfdt you can use:
-
-    make install [PREFIX=/path/to/install_dir]
-
-To disable building the python library, even if swig and Python are available,
-use:
-
-    make NO_PYTHON=1
-
-
-More work remains to support all of libfdt, including access to numeric
-values.
-
-
-Adding a new function to libfdt.h
----------------------------------
-
-The shared library uses libfdt/version.lds to list the exported functions, so
-add your new function there. Check that your function works with pylibfdt. If
-it cannot be supported, put the declaration in libfdt.h behind #ifndef SWIG so
-that swig ignores it.
-
-
-Tests
------
-
-Test files are kept in the tests/ directory. Use 'make check' to build and run
-all tests.
-
-If you want to adjust a test file, be aware that tree_tree1.dts is compiled
-and checked against a binary tree from assembler macros in trees.S. So
-if you change that file you must change tree.S also.
-
-
-Mailing list
-------------
-The following list is for discussion about dtc and libfdt implementation
-mailto:devicetree-compiler-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
-
-Core device tree bindings are discussed on the devicetree-spec list:
-mailto:devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..30212bc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# Device Tree Compiler and libfdt
+
+The source tree contains the Device Tree Compiler (dtc) toolchain for
+working with device tree source and binary files and also libfdt, a
+utility library for reading and manipulating the binary format.
+
+dtc and libfdt are maintained by:
+
+* [David Gibson `<david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>`](mailto:david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org)
+* [Jon Loeliger `<loeliger-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>`](mailto:loeliger-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org)
+
+## Python library
+
+A Python library wrapping libfdt is also available. To build this you
+will need to install `swig` and Python development files. On Debian
+distributions:
+
+```
+$ sudo apt-get install swig python3-dev
+```
+
+The library provides an `Fdt` class which you can use like this:
+
+```
+$ PYTHONPATH=../pylibfdt python3
+>>> import libfdt
+>>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').read())
+>>> node = fdt.path_offset('/subnode@1')
+>>> print(node)
+124
+>>> prop_offset = fdt.first_property_offset(node)
+>>> prop = fdt.get_property_by_offset(prop_offset)
+>>> print('%s=%s' % (prop.name, prop.as_str()))
+compatible=subnode1
+>>> node2 = fdt.path_offset('/')
+>>> print(fdt.getprop(node2, 'compatible').as_str())
+test_tree1
+```
+
+You will find tests in `tests/pylibfdt_tests.py` showing how to use each
+method. Help is available using the Python help command, e.g.:
+
+```
+$ cd pylibfdt
+$ python3 -c "import libfdt; help(libfdt)"
+```
+
+If you add new features, please check code coverage:
+
+```
+$ sudo apt-get install python3-coverage
+$ cd tests
+# It's just 'coverage' on most other distributions
+$ python3-coverage run pylibfdt_tests.py
+$ python3-coverage html
+# Open 'htmlcov/index.html' in your browser
+```
+
+The library can be installed with pip from a local source tree:
+
+```
+$ pip install . [--user|--prefix=/path/to/install_dir]
+```
+
+Or directly from a remote git repo:
+
+```
+$ pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
+```
+
+The install depends on libfdt shared library being installed on the
+host system first. Generally, using `--user` or `--prefix` is not
+necessary and pip will use the default location for the Python
+installation which varies if the user is root or not.
+
+You can also install everything via make if you like, but pip is
+recommended.
+
+To install both libfdt and pylibfdt you can use:
+
+```
+$ make install [PREFIX=/path/to/install_dir]
+```
+
+To disable building the python library, even if swig and Python are available,
+use:
+
+```
+$ make NO_PYTHON=1
+```
+
+More work remains to support all of libfdt, including access to numeric
+values.
+
+
+## Adding a new function to libfdt.h
+
+The shared library uses `libfdt/version.lds` to list the exported
+functions, so add your new function there. Check that your function
+works with pylibfdt. If it cannot be supported, put the declaration in
+`libfdt.h` behind `#ifndef SWIG` so that swig ignores it.
+
+
+## Tests
+
+Test files are kept in the `tests/` directory. Use `make check` to build and run
+all tests.
+
+If you want to adjust a test file, be aware that `tree_tree1.dts` is compiled
+and checked against a binary tree from assembler macros in `trees.S`. So
+if you change that file you must change `tree.S` also.
+
+
+## Mailing lists
+
+* The [devicetree-compiler](mailto:devicetree-compiler-u79uwXL29TY76Z2rM5mHXA@public.gmane.org)
+  list is for discussion about dtc and libfdt implementation.
+* Core device tree bindings are discussed on the
+  [devicetree-spec](mailto:devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org) list.
+
-- 
2.37.1

[PATCH 2/4] Remove Jon Loeliger from maintainers list

[David Gibson]

Jon hasn't been actively working on dtc maintenance for some years.

Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
---
 README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/README.md b/README.md
index 30212bc..36a3912 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,6 @@ utility library for reading and manipulating the binary format.
 dtc and libfdt are maintained by:
 
 * [David Gibson `<david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>`](mailto:david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org)
-* [Jon Loeliger `<loeliger-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>`](mailto:loeliger-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org)
 
 ## Python library
 
-- 
2.37.1

[PATCH 3/4] Split out information for contributors to CONTRIBUTING.md

[David Gibson]

README.md covers both general information for people using and building
the software, and more specific information for people contributing to
either dtc or libfdt.  Split out the latter information into its own file
for easier reference.

Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
---
 CONTRIBUTING.md | 25 +++++++++++++++++++++++++
 README.md       | 19 -------------------
 2 files changed, 25 insertions(+), 19 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..51f7a82
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,25 @@
+# Contributing to dtc or libfdt
+
+There are two ways to submit changes for dtc or libfdt:
+
+* Post patches directly to the the
+  [devicetree-compiler](mailto:devicetree-compiler-u79uwXL29TY76Z2rM5mHXA@public.gmane.org)
+  mailing list.
+* Submit pull requests via
+  [Github](https://github.com/dgibson/dtc/pulls)
+
+## Adding a new function to libfdt.h
+
+The shared library uses `libfdt/version.lds` to list the exported
+functions, so add your new function there. Check that your function
+works with pylibfdt. If it cannot be supported, put the declaration in
+`libfdt.h` behind `#ifndef SWIG` so that swig ignores it.
+
+## Tests
+
+Test files are kept in the `tests/` directory. Use `make check` to build and run
+all tests.
+
+If you want to adjust a test file, be aware that `tree_tree1.dts` is compiled
+and checked against a binary tree from assembler macros in `trees.S`. So
+if you change that file you must change `tree.S` also.
diff --git a/README.md b/README.md
index 36a3912..8f1a5d2 100644
--- a/README.md
+++ b/README.md
@@ -91,25 +91,6 @@ $ make NO_PYTHON=1
 More work remains to support all of libfdt, including access to numeric
 values.
 
-
-## Adding a new function to libfdt.h
-
-The shared library uses `libfdt/version.lds` to list the exported
-functions, so add your new function there. Check that your function
-works with pylibfdt. If it cannot be supported, put the declaration in
-`libfdt.h` behind `#ifndef SWIG` so that swig ignores it.
-
-
-## Tests
-
-Test files are kept in the `tests/` directory. Use `make check` to build and run
-all tests.
-
-If you want to adjust a test file, be aware that `tree_tree1.dts` is compiled
-and checked against a binary tree from assembler macros in `trees.S`. So
-if you change that file you must change `tree.S` also.
-
-
 ## Mailing lists
 
 * The [devicetree-compiler](mailto:devicetree-compiler-u79uwXL29TY76Z2rM5mHXA@public.gmane.org)
-- 
2.37.1

[PATCH 4/4] Add description of Signed-off-by lines

[David Gibson]

dtc and libfdt have been using Signed-off-by lines (as used in the Linux
kernel) for some time, like a lot of open source projects.  However
Uwe Kleine-König pointed out we never really stated what they mean in our
context.

Add information on what the S-o-b line means in CONTRIBUTING.md - this is
essentially a quote of the same information from the kernel documentation,
with some tweaks to make sense in the new context.

Suggested-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>
Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
---
 CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 51f7a82..940dd1a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,3 +23,57 @@ all tests.
 If you want to adjust a test file, be aware that `tree_tree1.dts` is compiled
 and checked against a binary tree from assembler macros in `trees.S`. So
 if you change that file you must change `tree.S` also.
+
+## Developer's Certificate of Origin
+
+Like many other projects, dtc and libfdt have adopted the "Developer's
+Certificate of Origin" (Signed-off-by) process created by the Linux
+kernel community to improve tracking of who did what.  Here's how it
+works (this is a very slight modification of the description from
+`Documentation/process/submitting-patches.rst` in the kernel tree):
+
+The sign-off is a simple line at the end of the explanation for the
+patch, which certifies that you wrote it or otherwise have the right
+to pass it on as an open-source patch.  The rules are pretty simple:
+if you can certify the below:
+
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+        (a) The contribution was created in whole or in part by me and I
+            have the right to submit it under the open source license
+            indicated in the file; or
+
+        (b) The contribution is based upon previous work that, to the best
+            of my knowledge, is covered under an appropriate open source
+            license and I have the right under that license to submit that
+            work with modifications, whether created in whole or in part
+            by me, under the same open source license (unless I am
+            permitted to submit under a different license), as indicated
+            in the file; or
+
+        (c) The contribution was provided directly to me by some other
+            person who certified (a), (b) or (c) and I have not modified
+            it.
+
+        (d) I understand and agree that this project and the contribution
+            are public and that a record of the contribution (including all
+            personal information I submit with it, including my sign-off) is
+            maintained indefinitely and may be redistributed consistent with
+            this project or the open source license(s) involved.
+
+then you just add a line saying::
+
+	Signed-off-by: Random J Developer <random-ld4jwAGwUXQYGaZWVHDzw80vGNN6ct63@public.gmane.org>
+
+using your real name (sorry, no pseudonyms or anonymous
+contributions.)  This will be done for you automatically if you use
+`git commit -s`.  Reverts should also include "Signed-off-by". `git
+revert -s` does that for you.
+
+Any further SoBs (Signed-off-by:'s) following the author's SoB are
+from people handling and transporting the patch, but were not involved
+in its development. SoB chains should reflect the **real** route a
+patch took as it was propagated to the maintainers, with the first SoB
+entry signalling primary authorship of a single author.
-- 
2.37.1

Re: [PATCH 4/4] Add description of Signed-off-by lines

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 1070 bytes --]

On Thu, Jul 28, 2022 at 05:53:48PM +1000, David Gibson wrote:
> dtc and libfdt have been using Signed-off-by lines (as used in the Linux
> kernel) for some time, like a lot of open source projects.  However
> Uwe Kleine-König pointed out we never really stated what they mean in our
> context.
> 
> Add information on what the S-o-b line means in CONTRIBUTING.md - this is
> essentially a quote of the same information from the kernel documentation,
> with some tweaks to make sense in the new context.
> 
> Suggested-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>
> Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>

Looks good, thanks.

Acked-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>

Will resend the patch that triggered that discussion with an S-o-b line
soon.

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | https://www.pengutronix.de/ |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH 4/4] Add description of Signed-off-by lines

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 1258 bytes --]

On Thu, Jul 28, 2022 at 06:08:00PM +0200, Uwe Kleine-König wrote:
> On Thu, Jul 28, 2022 at 05:53:48PM +1000, David Gibson wrote:
> > dtc and libfdt have been using Signed-off-by lines (as used in the Linux
> > kernel) for some time, like a lot of open source projects.  However
> > Uwe Kleine-König pointed out we never really stated what they mean in our
> > context.
> > 
> > Add information on what the S-o-b line means in CONTRIBUTING.md - this is
> > essentially a quote of the same information from the kernel documentation,
> > with some tweaks to make sense in the new context.
> > 
> > Suggested-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>
> > Signed-off-by: David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>
> 
> Looks good, thanks.
> 
> Acked-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>
> 
> Will resend the patch that triggered that discussion with an S-o-b line
> soon.

Great, thanks.

I've merged this series into the main branch.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]