mirror of
https://github.com/apache/nuttx.git
synced 2025-01-13 02:48:37 +08:00
convert INVIOLABLES.txt to markdown, add to docs
This commit is contained in:
Adam Feuer
Brennan Ashton
parent
389b45359d
commit
d655f47d13
7 changed files with 120 additions and 146 deletions
|
|
@ -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"
|
||||
|
|
|
|||
17
Documentation/Pipfile.lock
generated
17
Documentation/Pipfile.lock
generated
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
]
|
||||
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ Last Updated: |today|
|
|||
|
||||
Home <self>
|
||||
introduction/index.rst
|
||||
introduction/inviolables.rst
|
||||
quickstart/index.rst
|
||||
components/index.rst
|
||||
applications/index.rst
|
||||
|
|
|
|||
1
Documentation/introduction/inviolables.rst
Normal file
1
Documentation/introduction/inviolables.rst
Normal file
|
|
@ -0,0 +1 @@
|
|||
.. mdinclude:: ../../INVIOLABLES.md
|
||||
112
INVIOLABLES.md
Normal file
112
INVIOLABLES.md
Normal file
|
|
@ -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.
|
||||
125
INVIOLABLES.txt
125
INVIOLABLES.txt
|
|
@ -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.
|
||||
Loading…
Reference in a new issue