Initial commit to ONF Docs site
Change-Id: Ic882d6c7cc2f17a8fe74acee5cb70352b04aada2
diff --git a/devguide/conventions.rst b/devguide/conventions.rst
new file mode 100644
index 0000000..2e612af
--- /dev/null
+++ b/devguide/conventions.rst
@@ -0,0 +1,73 @@
+Development Conventions
+=======================
+
+ONF has many (over 300) software repositories as of 2022, and to effectively
+develop across all of these projects, the following development conventions are
+used.
+
+Strategy
+--------
+
+The general strategy for ONF software development is as follows:
+
+Make it easy to start contributing to any repo
+""""""""""""""""""""""""""""""""""""""""""""""
+
+A convention we've embraced in nearly all repos is to have a ``Makefile`` in
+their base directory, which has a few common targets:
+
+* ``make help``: Get a list of ``make`` targets
+* ``make build`` run
+* ``make test`` run all tests, as they'd be run in CI by a
+
+
+Most ``Makefiles`` use the GNU Make syntax variant.
+
+Automated tests should be identical for the developer and automation
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The CI test runner (Jenkins or similar) that performs automated testing should
+run the same tests in the same way that a developer would on their local
+system, by running ``make test``. There should be no (or very rare) cases where
+a test will pass locally but fail in CI.
+
+Additionally, this greatly simplifies the configuration of the test runner - it
+only needs to run ``make test``. In some cases, it may be necessary for the
+Makefile to include commands that generate Jenkins-consumable output, such as
+test results (usually in JUnit, xUnit, or TAP formats) or coverage information
+(usually in Cobertura XML format).
+
+
+Style, formatting, linting, license compliance should be automated
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Code review should be about the structure and design of the code, and should
+
+To that end, automated tools should be used that verify and conform the code to
+a specific convention and standard:
+
+* Formatting tools such as ``go fmt``, ``black`` and similar should be used to
+ conform code to style guidelines
+
+* Linting tools such as ``pylint``, ``yamllint``
+
+In the documentation space, spelling and other checks should also be performed.
+
+Versioning and Releasing Software
+---------------------------------
+
+Versioning software and performing releases are fundamentally for two audiences:
+
+1. Providing compatibility claims about
+2. Developers who use the
+
+Two common and recommended versioning schemes are;
+
+* SemVer
+* CalVer
+
+Division of responsibilities
+""""""""""""""""""""""""""""
+
+Automated tools should perform low-level versioning tasks like creating tags on
+repos.