--- /dev/null
+ Submitting patches or diff's to the FreeRADIUS project
+
+For a person or company who wishes to submit a change to the
+FreeRADIUS project, the process can sometimes be daunting if you're
+not familiar with "the system." This text is a collection of
+suggestions which can greatly increase the chances of your change
+being accepted.
+
+SECTION 1 - CREATING AND SENDING YOUR CHANGE
+
+ 1. "diff -u"
+
+ Use "diff -u" or "diff -urN" to create patches.
+
+ All changes to the source occur in the form of patches, as
+ generated by diff(1). When creating your patch, make sure to
+ create it in "unified diff" format, as supplied by the '-u'
+ argument to diff(1). Patches should be based in the root source
+ directory, not in any lower subdirectory.
+
+ To create a patch for a single file, it is often sufficient to do:
+
+ SRCTREE=/home/user/src/freeradiusd/
+ MYFILE=src/modules/rlm_foo/foo.c
+
+ cd $SRCTREE
+ cp $MYFILE $MYFILE.orig
+ vi $MYFILE # make your change
+ diff -u $MYFILE.orig $MYFILE > /tmp/patch
+
+ To create a patch for multiple files, you should unpack a
+ "vanilla", or unmodified source tree, and generate a diff
+ against your own source tree. For example:
+
+ MYSRC=/home/user/src/freeradiusd-feature/
+
+ gunzip freeradiusd-version.tar.gz
+ tar xvf freeradiusd-version.tar
+ diff -urN freeradiusd-version $MYSRC > ~/feature-version.patch
+
+ 2. Describe your changes.
+
+ Describe the technical detail of the change(s) your patch includes.
+
+ Be as specific as possible. The WORST descriptions possible
+ include things like "update file X", "bug fix for file X",
+ or "this patch includes updates for subsystem X. Please apply."
+
+ If your description starts to get long, that's a sign that you
+ probably need to split up your patch. See #3, next.
+
+ 3. Separate your changes.
+
+ Separate each logical change into its own patch.
+
+ For example, if your changes include both bug fixes and
+ performance enhancements for a single module, separate those
+ changes into two or more patches.
+
+ On the other hand, if you make a single change to numerous
+ files, group those changes into a single patch. Thus a single
+ LOGICAL change is contained within a single patch.
+
+ If one patch depends on another patch in order for a change to
+ be complete, that is OK. Simply note "this patch depends on
+ patch X" in your patch description.
+
+ 4. Select e-mail destination.
+
+ If you are on the developers mailing list, send the patch there.
+ freeradius-devel@info.cistron.nl
+
+ Otherwise, send the patch to 'patches@freeradius.org'
+
+ 5. No MIME, no links, no compression, no attachments. Just plain text.
+
+ The developers need to be able to read and comment on the
+ changes you are submitting. It is important for a developer to
+ be able to "quote" your changes, using standard e-mail tools, so
+ that they may comment on specific portions of your code.
+
+ For this reason, all patches should be submitting e-mail
+ "inline".
+
+ Do not attach the patch as a MIME attachment, compressed or
+ not. Many popular e-mail applications will not always transmit a
+ MIME attachment as plain text, making it impossible to comment
+ on your code. A MIME attachment also takes a bit more time to
+ process, decreasing the likelihood of your MIME-attached change
+ being accepted.
+
+ Compressed patches are generally rejected outright. If the
+ developer has to do additional work to read your patch, the odds
+ are that it will be ignored completely.
+
+ 5. E-mail size.
+
+ When sending patches, always follow step #5.
+
+ Large changes are not appropriate for mailing lists, and some
+ maintainers. If your patch, exceeds 40Kb in size, it is
+ preferred that you store your patch on an Internet-accessible
+ server, and provide instead a URL (link) pointing to your patch.
+
+ 6. Name the version of the server.
+
+ It is important to note, either in the subject line or in the
+ patch description, the server version to which this patch
+ applies.
+
+ 7. Don't get discouraged. Re-submit.
+
+ After you have submitted your change, be patient and wait. If
+ the patch is approved and applied, it will appear in the next
+ version of the server.
+
+ However, if your change doesn't appear in the next version of
+ the server, there could be any number of reasons. It's YOUR job
+ to narrow down those reasons, correct what was wrong, and submit
+ your updated change.
+
+ It is quite common a patch to be "dropped" without
+ comment. That's the nature of the system. If your patch is
+ dropped, it could be due to
+
+ A style issue (see section 2, below),
+ An e-mail formatting issue (see section item 5, above)
+ A technical problem with your change
+ Your patch got lost among other patches
+
+ When in doubt,
+
+SECTION 2 - HINTS, TIPS, AND TRICKS
+
+This section lists many of the common "rules" associated with code
+submitted to the kernel. There are always exceptions... but you must
+have a really good reason for doing so. You could probably call this
+section Linus Computer Science 101.
+
+ 1. Read the Documentation and follow the CodingStyle
+
+ The FreeRADIUS server has a common coding style. Tabs are 8
+ characters. There is whitespace in variable assignments.
+ (i = 1, NOT i=1).
+
+ When in doubt, format your code to look the same as code already
+ in the server. If your code deviates too much from the current
+ style, it is likely to be rejected without further review, and
+ without comment.
+
+ 2. #ifdefs are ugly
+
+ Code cluttered with ifdefs is difficult to read and
+ maintain. Don't do it. Instead, put your ifdefs in a header, and
+ conditionally define 'static inline' functions, or macros, which
+ are used in the code. Let the compiler optimize away the "no-op"
+ case.
+
+ Simple example, of poor code:
+
+ #ifdef CONFIG_MY_FUNKINESS
+ init_my_stuff(foo);
+ #endif
+
+ Cleaned-up example:
+
+ (in header)
+
+ #ifndef CONFIG_MY_FUNKINESS
+ static inline void init_my_stuff(char *foo) {}
+ #endif
+
+ (in the code itself)
+
+ ...
+ init_my_stuff(dev);
+ ...
+
+ 3. 'static inline' is better than a macro
+
+ Static inline functions are greatly preferred over macros. They
+ provide type safety, have no length limitations, no formatting
+ limitations, and under gcc they are as cheap as macros.
+
+ Macros should only be used for cases where a static inline is
+ clearly suboptimal [there a few, isolated cases of this in fast
+ paths], or where it is impossible to use a static inline
+ function [such as string-izing].
+
+ 'static inline' is preferred over 'static __inline__', 'extern
+ inline', and 'extern __inline__'.
+
+ 4. Don't over-design.
+
+ Don't try to anticipate nebulous future cases which may or may
+ not be useful: "Make it as simple as you can, and no simpler"
+
+ Split up functionality as much as possible. If your code needs
+ to do two unrelated things, write two functions. Mashing two
+ kinds of work into one function makes the server difficult to
+ debug and maintain.
+
+ See the 'coding-methods.txt' document in this directory for
+ further description of coding methods.
--- /dev/null
+ Helpful coding methods
+ by Alan DeKok <aland@ox.org>
+
+ The following is a short set of guidelines to follow while
+programming. It does not address coding styles, function naming
+methods, or debugging methods. Rather, it describes the processes
+which SHOULD go on in the programmers mind, while he is programming.
+
+ Coding standards apply to function names, the look of the code, and
+coding consistency. Coding methods apply to the daily practices used
+by the programmer to write code.
+
+
+
+1. Comment your code.
+
+ If you don't, you'll be forced to debug it 6 months later, when
+ you have no clue as to what it's doing.
+
+ If someone REALLY hates you, you'll be forced to debug
+ un-commented code that someone else wrote. You don't want to do
+ that.
+
+
+2. Give things reasonable names.
+
+ Variables and functions should have names. Calling them 'x',
+ 'xx', and 'xxx' makes your life hell. Even 'foo' and 'i' are
+ problematic.
+
+
+3. Check input parameters in the functions you write.
+
+ Your function CANNOT do anything right if the user passed in
+ garbage, and you were too lazy to check for garbage input.
+
+ assert() is ugly. Use it.
+
+ GIGO is wrong. If your function gets garbage input, it
+ should complain loudly and with great descriptiveness.
+
+
+4. Write useful error messages.
+
+ "Function failed" is useless as an error message. It makes
+ debugging the code impossible without source-level instrumentation.
+
+ If you're going to instrument the code at source level for error
+ messages, leave the error messages there, so the next sucker won't
+ have to do the same work all over again.
+
+
+5. Check error conditions from the functions you call.
+
+ Your function CANNOT do anything right if you called another
+ function, and they gave you garbage output.
+
+ One of the most common mistakes is:
+
+ fp = fopen(...);
+ fgetc(fp); /* core dumps! */
+
+ If the programmer had bothered to check for a NULL fp (error
+ condition), then he could have produced a DESCRIPTIVE error
+ message, instead of having his program core dump.
+
+
+6. Core dumps are for weenies.
+
+ If your program core dumps accidentally, you're a bad programmer.
+ You don't know what your program is doing, or what it's supposed
+ to be doing when anything goes wrong.
+
+ If it hits an assert() and calls abort(), you're a genius. You've
+ though ahead to what MIGHT go wrong, and put in an assertion to
+ ensure that it fails in a KNOWN MANNER when something DOES go
+ wrong. (As it usually does...)
+
+
+7. Initialize your variables.
+
+ memset() is your friend. 'ptr = NULL' is nice, too.
+
+ Having variables containing garbage values makes it easy for the
+ code to do garbage things. The contents of local variables are
+ inputs to your function. See #3.
+
+ It's also nearly impossible for you to debug any problems, as you
+ can't tell the variables with garbage values from the real ones.
+
+
+8. Don't allow buffer over-runs.
+
+ They're usually accidental, but they cause core dumps.
+ strcpy() and strcat() are ugly. Use them under duress.
+
+ sizeof() is your friend.
+
+
+9. 'const' is your friend.
+
+ If you don't mean to modify an input structure to your function,
+ declare it 'const'. Declare string constants 'const'. It can't
+ hurt, and it allows more errors to be found at compile time.
+
+ Use 'const' everywhere. Once you throw a few into your code, and
+ have it save you from stupid bugs, you'll blindly throw in 'const'
+ everywhere. It's a life-saver.
+
+
+10. Use C compiler warnings.
+
+ Turn on all of the C compiler warnings possible. You might have
+ to turn some off due to broken system header files, though. But
+ the more warnings the merrier.
+
+ Getting error messages at compile time is much preferable to
+ getting core dumps at run time. See #7.
+
+ Notice that the C compiler error messages are helpful? You should
+ write error messages like this, too. See #4.
+
+
+11. Test your code.
+
+ Unless you're Donald Knuth, you write buggy code. You'll never
+ find all of the bugs in your code unless you write a test program
+ for it.
+
+ This also means that you'll have to write your code so that it
+ will be easily testable. As a result, it will look better, and be
+ easier to debug.
projects / freeradius.git / commitdiff