diff --git a/Documentation/Pipfile b/Documentation/Pipfile index 5b34c233d5..427173299c 100644 --- a/Documentation/Pipfile +++ b/Documentation/Pipfile @@ -6,10 +6,9 @@ verify_ssl = true [dev-packages] [packages] -recommonmark = "*" -m2r2 = "==0.2.5" -Sphinx = "==3.2.1" -sphinx-rtd-theme = "==0.5.0" +m2r2 = "*" +sphinx_rtd_theme = "*" +Sphinx = "*" [requires] python_version = "3.7" diff --git a/Documentation/Pipfile.lock b/Documentation/Pipfile.lock index 69cc0824b4..69ae687bea 100644 --- a/Documentation/Pipfile.lock +++ b/Documentation/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "bac8693c975b556322effc997daf7c6257237330d63185d0729a8dd5b3d12375" + "sha256": "211b83bbd887f84b143e56bfb81a0871f186d934b0c973032464e70f4138d79f" }, "pipfile-spec": 6, "requires": { @@ -45,13 +45,6 @@ ], "version": "==3.0.4" }, - "commonmark": { - "hashes": [ - "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60", - "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9" - ], - "version": "==0.9.1" - }, "docutils": { "hashes": [ "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af", @@ -169,14 +162,6 @@ ], "version": "==2020.1" }, - "recommonmark": { - "hashes": [ - "sha256:29cd4faeb6c5268c633634f2d69aef9431e0f4d347f90659fd0aab20e541efeb", - "sha256:2ec4207a574289355d5b6ae4ae4abb29043346ca12cdd5f07d374dc5987d2852" - ], - "index": "pypi", - "version": "==0.6.0" - }, "requests": { "hashes": [ "sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b", diff --git a/Documentation/conf.py b/Documentation/conf.py index 296791f8b7..0e9d8be48a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -52,7 +52,7 @@ extensions = [ "sphinx_rtd_theme", "m2r2", 'sphinx.ext.autosectionlabel', - 'sphinx.ext.todo' + 'sphinx.ext.todo', ] source_suffix = [ '.rst', '.md' ] @@ -115,3 +115,4 @@ c_id_attributes = [ 'CODE', 'noreturn_function' ] + diff --git a/Documentation/index.rst b/Documentation/index.rst index 65dd9ad08e..a221e39b8b 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -21,6 +21,7 @@ Last Updated: |today| Home introduction/index.rst + introduction/inviolables.rst quickstart/index.rst components/index.rst applications/index.rst diff --git a/Documentation/introduction/inviolables.rst b/Documentation/introduction/inviolables.rst new file mode 100644 index 0000000000..c3ba45cee1 --- /dev/null +++ b/Documentation/introduction/inviolables.rst @@ -0,0 +1 @@ +.. mdinclude:: ../../INVIOLABLES.md diff --git a/INVIOLABLES.md b/INVIOLABLES.md new file mode 100644 index 0000000000..11c704e696 --- /dev/null +++ b/INVIOLABLES.md @@ -0,0 +1,112 @@ +# The Inviolable Principles of Nuttx + +These are properties of NuttX that we can be certain of for all time: + +## Definition + +*in·vi·o·la·ble* +/inˈvīələbəl/ + +adjective +adjective: inviolable + + never to be broken, infringed, or dishonored. + + "an inviolable rule of chastity" + + synonyms: inalienable, absolute, untouchable, unalterable, + unchallengeable, unbreakable, impregnable; sacrosanct, + sacred, holy, hallowed; rare intemerate + + "the inviolable right to life" + +Source: Oxford Dictionary of the English Language + +## Strict POSIX compliance + + - Strict conformance to the portable standard OS interface as defined at + OpenGroup.org. + - A deeply embedded system requires some special support. Special + support must be minimized. + - The portable interface must never be compromised only for the sake of + expediency. + - Expediency or even improved performance are not justifications for + violation of the strict POSIX interface. + +## Modular Architecture + + - The internal modular architecture of the OS must be maintained. + - This means formalizing and documenting all internal interfaces (in the + porting guide), minimal use of global variables at the interface, and + only well defined functional interfaces. + +## Clear, Consistent, Standardized Coding Style + + - Strict conformance to the NuttX coding style. No "revolutionary" + changes to the coding standard (but perhaps some "evolutionary" + changes). + - Personal or organizational preference is not a justification for a + coding style change. + - Nothing can come into NuttX that does not follow the coding standard. + - Expediency is not a justification for violating the coding standard. + + The NuttX coding standard can be found here: + https://nuttx.apache.org/docs/latest/contributing/coding_style.html + +## Open and Unencumbered License + + - Currently BSD 3-clause or compatible: BSD 3-clause with constraints, + BSD 3 and 4 clause, MIT, public domain. + - Other unencumbered licenses such as Apache may be considered. + NuttX will never be licensed under a restrictive, "Copyleft" license. + +## All Users Matter + + - All support must apply equally to all supported platforms. At present + this includes Linux, Windows MSYS, Windows Cygwin, Windows Ubuntu, + Windows native, macOS, Solaris, and FreeBSD. No tool/environment + solutions will be considered that limit the usage of NuttX on any of + the supported platforms. + - Inclusive rather than exclusive. + - Hobbyists are valued users of the OS including retro computing hobbyists + * and DIY “Maker” hobbyists. + - Supported toolchains: GCC, Clang, SDCC, ZiLOG ZDS-II (c89), IAR. + Others? + - No changes to build system should limit use of NuttX by any user. + - Simplifying things for one user does not justify excluding another user. + - We should seek to expand the NuttX user base, not to limit it for + reasons of preference or priority. + - We must resist the pull to make NuttX into a Linux-only, GCC-only, and + ARM-only solution. + +## NuttX Branding + + - The official name of authentic Nuttx will always be "NuttX". + - This name is trademarked and may not be used by other OSs or forks of + NuttX. + +## The Enemies + +### No Short Cuts + + - Doing things the easy way instead of the correct way. + - Reducing effort at the expense of Quality, Portability, or + Consistency. + - Focus on the values of the organization, not the values of the Open + Source project. Need to support both. + - It takes work to support the Inviolables. There are no shortcuts. + +### Sometimes Code Duplication is OK + + - Sometimes is better to duplicate some logic than to introduce coupling. + +### Keep the Big Picture + + - Too much focus on solving the problem in hand, loss of the Big Picture. + - Insufficient understanding of the architectural principles. + +### Conform to Standards + + - Changing things only to suit a personal or organizational preference. + - Inflexibility, Inability to adapt. + - Not Invented Here (NIH) syndrome. diff --git a/INVIOLABLES.txt b/INVIOLABLES.txt deleted file mode 100644 index 711c09d3a7..0000000000 --- a/INVIOLABLES.txt +++ /dev/null @@ -1,125 +0,0 @@ -The Inviolable Principles of Nuttx -================================== - -These are properties of NuttX that we can be certain of for all time: - -Definition ----------- - -*in·vi·o·la·ble* -/inˈvīələbəl/ - -adjective -adjective: inviolable - - never to be broken, infringed, or dishonored. - - "an inviolable rule of chastity" - - synonyms: inalienable, absolute, untouchable, unalterable, - unchallengeable, unbreakable, impregnable; sacrosanct, - sacred, holy, hallowed; rare intemerate - - "the inviolable right to life" - -Source: Oxford Dictionary of the English Language - -Strict POSIX compliance ------------------------ - - o Strict conformance to the portable standard OS interface as defined at - OpenGroup.org. - o A deeply embedded system requires some special support. Special - support must be minimized. - o The portable interface must never be compromised only for the sake of - expediency. - o Expediency or even improved performance are not justifications for - violation of the strict POSIX interface. - -Modular Architecture --------------------- - - o The internal modular architecture of the OS must be maintained. - o This means formalizing and documenting all internal interfaces (in the - porting guide), minimal use of global variables at the interface, and - only well defined functional interfaces. - -Clear, Consistent, Standardized Coding Style --------------------------------------------- - - o Strict conformance to the NuttX coding style. No "revolutionary" - changes to the coding standard (but perhaps some "evolutionary" - changes). - o Personal or organizational preference is not a justification for a - coding style change. - o Nothing can come into NuttX that does not follow the coding standard. - o Expediency is not a justification for violating the coding standard. - - The NuttX coding standard can be found here: - http://www.nuttx.org/doku.php?id=documentation:codingstandard - -Open and Unencumbered License ------------------------------ - - o Currently BSD 3-clause or compatible: BSD 3-clause with constraints, - BSD 3 and 4 clause, MIT, public domain. - o Other unencumbered licenses such as Apache may be considered. - NuttX will never be licensed under a restrictive, "Copyleft" license. - -All Users Matter ----------------- - - o All support must apply equally to all supported platforms. At present - this includes Linux, Windows MSYS, Windows Cygwin, Windows Ubuntu, - Windows native, macOS, Solaris, and FreeBSD. No tool/environment - solutions will be considered that limit the usage of NuttX on any of - the supported platforms. - o Inclusive rather than exclusive. - o Hobbyists are valued users of the OS including retro computing hobbyists - * and DIY “Maker” hobbyists. - o Supported toolchains: GCC, Clang, SDCC, ZiLOG ZDS-II (c89), IAR. - Others? - o No changes to build system should limit use of NuttX by any user. - o Simplifying things for one user does not justify excluding another user. - o We should seek to expand the NuttX user base, not to limit it for - reasons of preference or priority. - o We must resist the pull to make NuttX into a Linux-only, GCC-only, and - ARM-only solution. - -NuttX Branding --------------- - - o The official name of authentic Nuttx will always be "NuttX". - o This name is trademarked and may not be used by other OSs or forks of - NuttX. - -The Enemies -=========== - -No Short Cuts -------------- - - o Doing things the easy way instead of the correct way. - o Reducing effort at the expense of Quality, Portability, or - Consistency. - o Focus on the values of the organization, not the values of the Open - Source project. Need to support both. - o It takes work to support the Inviolables. There are no shortcuts. - -Sometimes Code Duplication is OK --------------------------------- - - o Sometimes is better to duplicate some logic than to introduce coupling. - -Keep the Big Picture --------------------- - - o Too much focus on solving the problem in hand, loss of the Big Picture. - o Insufficient understanding of the architectural principles. - -Conform to Standards --------------------- - - o Changing things only to suite a personal or organizational preference. - o Inflexibility, Inability to adapt. - o Not Invented Here (NIH) syndrome.