Revised coding and development policies
authorBarret Rhoden <brho@cs.berkeley.edu>
Tue, 14 Sep 2010 17:55:44 +0000 (10:55 -0700)
committerKevin Klues <klueska@cs.berkeley.edu>
Thu, 3 Nov 2011 00:35:54 +0000 (17:35 -0700)
CODING [deleted file]
Documentation/CodingPolicy [new file with mode: 0644]
LICENSE
OVERVIEW [deleted file]
README [deleted file]

diff --git a/CODING b/CODING
deleted file mode 100644 (file)
index 03456d9..0000000
--- a/CODING
+++ /dev/null
@@ -1,35 +0,0 @@
-ROS CODING STANDARDS
-
-It's easier on everyone if all authors working on a shared
-code base are consistent in the way they write their programs.
-We have the following conventions in our code:
-
-* No space after the name of a function in a call
-  For example, printf("hello") not printf ("hello").
-
-* One space after keywords "if", "for", "while", "switch".
-  For example, if (x) not if(x).
-
-* Space before braces.
-  For example, if (x) { not if (x){.
-
-* Function names are all lower-case separated by underscores.
-
-* Beginning-of-line indentation via tabs, not spaces.
-
-* Preprocessor macros are always UPPERCASE.
-  There are a few grandfathered exceptions: assert, panic,
-  static_assert, offsetof.
-
-* Pointer types have spaces: (uint16_t *) not (uint16_t*).
-
-* Multi-word names are lower_case_with_underscores.
-
-* Comments in imported code are usually C /* ... */ comments.
-  Comments in new code are C++ style //.
-
-* In a function definition, the function name starts a new line.
-  Then you can grep -n '^foo' */*.c to find the definition of foo.
-
-* Functions that take no arguments are declared f(void) not f().
-
diff --git a/Documentation/CodingPolicy b/Documentation/CodingPolicy
new file mode 100644 (file)
index 0000000..6bb4397
--- /dev/null
@@ -0,0 +1,120 @@
+ROS Development Policies
+------------------------------------
+This document will talk about coding standards, version control, and
+contribution policies.
+
+Our coding standard is similar to the Linux kernel style (but with a tabstop of
+4), so when in doubt, do what they do.
+- No spaces after the name of a function in a call.  For example,
+  printk("hello") not printk ("hello").
+
+- Functions that take no arguments are declared f(void) not f().
+
+- Function names are all lower-case, separated by underscores.
+
+- One space after commas.  For example foo(x, y, z), not foo(x,y,z);
+
+- One space after keywords "if", "for", "while", "switch".  For example, if
+  (x) not if(x).
+
+- Space before braces.  For example, if (x) { not if (x){.
+
+- For if/while/etc, the opening brace is on the same line as the if.  If you
+  have just one line, no brace is necessary.  If you have an if / else clause,
+  and one of them has braces, put braces on both.  An else line should start
+  with a brace.
+
+- Beginning-of-line indentation via tabs, not spaces.  Use spaces for
+  additional formatting (such as lining up text when word wrapping).
+
+- Preprocessor macros are usually upper-case.  Try to avoid using macros
+  unless necessary (I prefer static inlines).
+
+- Pointer declarations have the * on the variable.  void *x, not void* x.
+
+- Multi-word names are lower_case_with_underscores.  Keep your names short,
+  especially for local variables.
+
+- 'Permanent' comments in are C /* ... */ comments.  Only use C++ style (//)
+  for temporary commenting-out, such as if you want to not call a function.
+  If you want to block out large chunks of code, use #if 0 ... #endif
+
+- In a function definition, the function name shoud NOT start a new line.  Old
+  code incorrectly does this, and should be changed over time.
+- Feel free to use gotos, especially in functions that have cleanup before
+  they exit, or in other places that enhance readability.
+
+- 80 characters per line.  When you wrap, try to line things up so they make
+  sense, such as space-indenting so function arguments line up vertically.
+
+- Do not typedef structs.  You can typedef function pointers when convenient.
+  Keep in mind that typedefs require people to look up the real type when they
+  analyze the code.
+
+- Try to avoid making lots of separate files or extravagant directory
+  hierarchies.  Keep in mind that people will need to work with and find these
+  files (even via tab completion, it can be a pain).
+
+Version Control: (git)
+- Git allows us to do a lot of cool things.  One of its primary purposes is to
+  provide a means for us to review each others code.
+
+- Do not merge.  You should rebase your commits on top of the latest branch,
+  then do a fast-forward merge.  You need to figure this out before working
+  with the main repo.  Merges can be appropriate, but ask brho first.  If you
+  are new to git, then odds are you should do the rebase/merge approach.
+
+- Do not commit crappy commits.  Hold on to your commits for a little while
+  before pushing, and if a problem appears in a branch that only you are using,
+  you should go back and amend those commits.  git rebase and git commit
+  --amend are your friend.
+
+- Do not commit to "share code."  If two people are working on the same code
+  and want to pass code from machine to machine, do not use a real branch from
+  the origin repo.  You can do whatever on your own machines (or even in a
+  temporary branch on the scm machine), but the version of the code submitted
+  to the mainline must not have those crappy commits.
+
+- Commit messages consist of one short line, followed by an empty line, and
+  then a descriptive message (word wrapped).  Most editors (like vi) will help
+  you with this.
+
+- Once you've pushed a branch to the origin, you normally should not reset it -
+  if the problem is minor, fix it later.  If you do it right away, it is
+  usually not a big deal.  If you broke the repo, fix it, and you should
+  probably send something to ros-kernel@.
+
+- You ought to use gitk --all, or a similar program, to help visualize what is
+  going on with the tree.
+
+- Your commits should be of a reasonable size.  Try to isolate your commits to
+  small, easily verifiable changes.  Each commit must compile, but you don't
+  want to change everything in one commit.  Put another way, one commit that
+  can be decoupled into smaller ones ought to be broken up.
+
+- Likewise, don't do a commit just to change irrelevant things, such as turning
+  off a printk or adjusting your manager() function (unless there's a good
+  reason).  You just pollute the commit stream.
+
+Contributing:
+- Currently, we are not accepting unsolicited, large contributions.  If you
+  have something in mind, contact us and we'll see how we can make it work.
+  If you want your work to be merged, you should check with us before starting
+  a project that may be incompatible with our system and goals.
+
+- We will accept bug fixes.  Until we sort out the copyrights, if you want us
+  to accept your patch, you'll need to assign your copyright to the Regeants of
+  the University of California, which shouldn't be an issue for an UC Berkeley
+  personnel.
+
+- Expect your code to be audited by the appropriate subsystem maintainer.
+  Basically, this means that if it is related to the sparc port, you need to
+  make Andrew happy.  Otherwise, you need to make Barret happy.
+
+- Despite being a research project, we make every effort to do things the
+  proper way.  We are extremely reluctant to allow "ghetto hacks", especially
+  the type that pop up near paper deadlines.  The appropriate way to deal with
+  this is to have a separate branch for all the shameful commits you have, and
+  after your deadlines have passed, you pick and choose which commits to apply
+  to the real branch in a way that does not violate our standards.
diff --git a/LICENSE b/LICENSE
index 6a0270c..a778328 100644 (file)
--- a/LICENSE
+++ b/LICENSE
@@ -1,3 +1,10 @@
+ROS is *NOT* licensed for any form of distribution.  We'll eventually license
+it, once we sort through the mess of contributions.
+
+
+The old JOS code came with the following:
+-----------------------------------------
+
 Most of the source files in this directory are derived from the Exokernel,
 which is:
 
diff --git a/OVERVIEW b/OVERVIEW
deleted file mode 100644 (file)
index e69de29..0000000
diff --git a/README b/README
deleted file mode 100644 (file)
index e69de29..0000000