[PATCH docs] Add doc for contribution guidelines

[PATCH docs] Add doc for contribution guidelines

[OpenBMC Patches]

Start somewhere to document our development conventions.

Signed-off-by: Jeremy Kerr <jk@ozlabs.org>

https://github.com/openbmc/docs/pull/10

Jeremy Kerr (1):
  Add doc for contribution guidelines

 contributing.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 contributing.md

-- 
2.6.4

[PATCH docs] Add doc for contribution guidelines

[OpenBMC Patches]

From: Jeremy Kerr <jk@ozlabs.org>

Start somewhere to document our development conventions.

Signed-off-by: Jeremy Kerr <jk@ozlabs.org>
---
 contributing.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 contributing.md

diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..bf36363
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,145 @@
+Contributing to OpenBMC
+=======================
+
+Here's a little guide to working on OpenBMC. This document will always be
+a work-in-progress, feel free to propose changes.
+
+Authors:
+
+  Jeremy Kerr <jk@ozlabs.org>
+
+Structure
+---------
+
+OpenBMC has quite a module structure, consisting of small daemons with a
+limited set of responsibilities. These communicate over dbus with other
+components, to implement the complete BMC system.
+
+The BMC's interfaces to the external world are typically through a separate
+daemon, which then translates those requests to dbus messages.
+
+These separate projects are then compiled into the final system by the
+overall 'openbmc' build infrastructure.
+
+For future development, keep this design in mind. Components' functionality
+should be logically grouped, and keep related parts together where it
+makes sense.
+
+Coding style
+------------
+
+Components of the OpenBMC sources should have consistent style.
+
+For C code, we typically use the Linux coding style, which is documented at:
+
+  http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle
+
+In short:
+
+  - Indent with tabs instead of spaces, set at 8 columns
+
+  - 80-column lines
+
+  - Opening braces on the end of a line, except for functions
+
+
+Submitting changes
+------------------
+
+We use git for almost everything. Changes should be sent as patches to their
+relevant source tree - or a git pull request for convenience.
+
+Each commit should be a self-contained logical unit, and smaller patches are
+usually better. However, if there is no clear division, a larger patch is
+okay. During development, it can be useful to consider how your change can be
+submitted as logical units.
+
+Commit messages are important. They should describe why the change is needed,
+and what effects it will have on the system. Do not describe the actual
+code change made by the patch; that's what the patch itself is for.
+
+Use your full name for contributions, and include a "Signed-off-by" line,
+to indicate that you agree to the Developers Certificate of Origin (see below).
+
+Ensure that your patch doesn't change unrelated areas. Be careful of
+accidental whitespace changes - this makes review unnecessarily difficult.
+
+The guidelines in the Linux kernel are very useful:
+
+ http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches
+
+Your contribution will generally need to be reviewed before being accepted.
+
+Avoid references to non-public resources
+----------------------------------------
+
+Code and commit messages should not refer to companies' internal documents
+or systems (including bug trackers). Other developers may not have access to
+these, making future maintenance difficult.
+
+
+Best practices for dbus interfaces
+----------------------------------
+
+ * New dbus interfaces should be reusable
+
+ * Type signatures should and use the simplest types possible, appropriate
+   for the data passed. For example, don't pass numbers as ASCII strings.
+
+ * New dbus interfaces should be documented in the 'docs' repository, at:
+
+     https://github.com/openbmc/docs/blob/master/dbus-interfaces.md
+
+See also: http://dbus.freedesktop.org/doc/dbus-api-design.html
+
+
+Best practices for C
+--------------------
+
+There are numerous resources avaialble elsewhere, but a few items that are
+relevant to OpenBMC work:
+
+ * You almost never need to use `system(<some shell pipeline>)`. Reading and
+   writing from files should be done with the appropriate system calls.
+
+   Generally, it's much better to use `fork(); execve()` if you do need to
+   spawn a process, especially if you need to provide variable arguments.
+
+ * Use the `stdint` types (eg, `uint32_t`, `int8_t`) for data that needs to be
+   a certain size. Use the `PRIxx` macros for printf, if necessary.
+
+ * Don't assume that `char` is signed or unsigned.
+
+ * Beware of endian considerations when reading to & writing from
+   C types
+
+ * Declare internal-only functions as `static`, declare read-only data
+   as `const` where possble.
+
+
+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.
-- 
2.6.4

Re: [PATCH docs] Add doc for contribution guidelines

[Daniel Axtens]

OpenBMC Patches <openbmc-patches@stwcx.xyz> writes:

> From: Jeremy Kerr <jk@ozlabs.org>
>
> Start somewhere to document our development conventions.

This indeed looks like an excellent start! :)

> +  - Opening braces on the end of a line, except for functions

Huh, I had forgotten that... Good to be reminded!

Regards,
Daniel Axtens

Re: [PATCH docs] Add doc for contribution guidelines

[Andrew Donnellan]

On 14/01/16 20:10, OpenBMC Patches wrote:
> +Use your full name for contributions, and include a "Signed-off-by" line,
> +to indicate that you agree to the Developers Certificate of Origin (see below).

"Developer's", for consistency :)

Otherwise looks excellent.

Reviewed-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com>

-- 
Andrew Donnellan              Software Engineer, OzLabs
andrew.donnellan@au1.ibm.com  Australia Development Lab, Canberra
+61 2 6201 8874 (work)        IBM Australia Limited

Re: [PATCH docs] Add doc for contribution guidelines

[Stewart Smith]

OpenBMC Patches <openbmc-patches@stwcx.xyz> writes:
> From: Jeremy Kerr <jk@ozlabs.org>
>
> Start somewhere to document our development conventions.
>
> Signed-off-by: Jeremy Kerr <jk@ozlabs.org>

Reviewed-by: Stewart Smith <stewart@linux.vnet.ibm.com>

-- 
Stewart Smith
OPAL Architect, IBM.

Re: [PATCH docs] Add doc for contribution guidelines

[Andrew Jeffery]

On 14/01/2016 7:40 PM, OpenBMC Patches <openbmc-patches@stwcx.xyz> wrote:
>
> From: Jeremy Kerr <jk@ozlabs.org>
>
> Start somewhere to document our development conventions.

Looks good to me, much better to spell out expectations than leave them to be implied.

Reviewed-by: Andrew Jeffery <andrew@aj.id. au>

>
> Signed-off-by: Jeremy Kerr <jk@ozlabs.org>
> ---
> contributing.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 145 insertions(+)
> create mode 100644 contributing.md
>
> diff --git a/contributing.md b/contributing.md
> new file mode 100644
> index 0000000..bf36363
> --- /dev/null
> +++ b/contributing.md
> @@ -0,0 +1,145 @@
> +Contributing to OpenBMC
> +=======================
> +
> +Here's a little guide to working on OpenBMC. This document will always be
> +a work-in-progress, feel free to propose changes.
> +
> +Authors:
> +
> +  Jeremy Kerr <jk@ozlabs.org>
> +
> +Structure
> +---------
> +
> +OpenBMC has quite a module structure, consisting of small daemons with a
> +limited set of responsibilities. These communicate over dbus with other
> +components, to implement the complete BMC system.
> +
> +The BMC's interfaces to the external world are typically through a separate
> +daemon, which then translates those requests to dbus messages.
> +
> +These separate projects are then compiled into the final system by the
> +overall 'openbmc' build infrastructure.
> +
> +For future development, keep this design in mind. Components' functionality
> +should be logically grouped, and keep related parts together where it
> +makes sense.
> +
> +Coding style
> +------------
> +
> +Components of the OpenBMC sources should have consistent style.
> +
> +For C code, we typically use the Linux coding style, which is documented at:
> +
> +  http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle
> +
> +In short:
> +
> +  - Indent with tabs instead of spaces, set at 8 columns
> +
> +  - 80-column lines
> +
> +  - Opening braces on the end of a line, except for functions
> +
> +
> +Submitting changes
> +------------------
> +
> +We use git for almost everything. Changes should be sent as patches to their
> +relevant source tree - or a git pull request for convenience.
> +
> +Each commit should be a self-contained logical unit, and smaller patches are
> +usually better. However, if there is no clear division, a larger patch is
> +okay. During development, it can be useful to consider how your change can be
> +submitted as logical units.
> +
> +Commit messages are important. They should describe why the change is needed,
> +and what effects it will have on the system. Do not describe the actual
> +code change made by the patch; that's what the patch itself is for.
> +
> +Use your full name for contributions, and include a "Signed-off-by" line,
> +to indicate that you agree to the Developers Certificate of Origin (see below).
> +
> +Ensure that your patch doesn't change unrelated areas. Be careful of
> +accidental whitespace changes - this makes review unnecessarily difficult.
> +
> +The guidelines in the Linux kernel are very useful:
> +
> + http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches
> +
> +Your contribution will generally need to be reviewed before being accepted.
> +
> +Avoid references to non-public resources
> +----------------------------------------
> +
> +Code and commit messages should not refer to companies' internal documents
> +or systems (including bug trackers). Other developers may not have access to
> +these, making future maintenance difficult.
> +
> +
> +Best practices for dbus interfaces
> +----------------------------------
> +
> + * New dbus interfaces should be reusable
> +
> + * Type signatures should and use the simplest types possible, appropriate
> +   for the data passed. For example, don't pass numbers as ASCII strings.
> +
> + * New dbus interfaces should be documented in the 'docs' repository, at:
> +
> +     https://github.com/openbmc/docs/blob/master/dbus-interfaces.md
> +
> +See also: http://dbus.freedesktop.org/doc/dbus-api-design.html
> +
> +
> +Best practices for C
> +--------------------
> +
> +There are numerous resources avaialble elsewhere, but a few items that are
> +relevant to OpenBMC work:
> +
> + * You almost never need to use `system(<some shell pipeline>)`. Reading and
> +   writing from files should be done with the appropriate system calls.
> +
> +   Generally, it's much better to use `fork(); execve()` if you do need to
> +   spawn a process, especially if you need to provide variable arguments.
> +
> + * Use the `stdint` types (eg, `uint32_t`, `int8_t`) for data that needs to be
> +   a certain size. Use the `PRIxx` macros for printf, if necessary.
> +
> + * Don't assume that `char` is signed or unsigned.
> +
> + * Beware of endian considerations when reading to & writing from
> +   C types
> +
> + * Declare internal-only functions as `static`, declare read-only data
> +   as `const` where possble.
> +
> +
> +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.
> -- 
> 2.6.4
>
> _______________________________________________
> openbmc mailing list
> openbmc@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/openbmc

Re: [PATCH docs] Add doc for contribution guidelines

[Sam Mendoza-Jonas]

On Thu, Jan 14, 2016 at 03:10:09AM -0600, OpenBMC Patches wrote:
> From: Jeremy Kerr <jk@ozlabs.org>
<snip>
> +OpenBMC has quite a module structure, consisting of small daemons with a
> +limited set of responsibilities. These communicate over dbus with other
> +components, to implement the complete BMC system.
<snip>

Just a nitpick: should that be s/module/modular?

Re: [PATCH docs] Add doc for contribution guidelines

[Jeremy Kerr]

Hi Sam,

> <snip>
>> +OpenBMC has quite a module structure, consisting of small daemons with a
>> +limited set of responsibilities. These communicate over dbus with other
>> +components, to implement the complete BMC system.
> <snip>
>
> Just a nitpick: should that be s/module/modular?

Yes, it should be. I'll queue this change with any other small fixes 
that come in.

Thanks!



Jeremy