X-Git-Url: https://git.openafs.org/?p=openafs.git;a=blobdiff_plain;f=CODING;h=b1e12c764c5fa03da16d41d580e614a826103510;hp=7ad8170789b5f579b22548813e32b1160e820e70;hb=0adad43d8e400e273ae243cc98ab1503673eb8be;hpb=04c7ed855ef78e1d1a15821ffff5fe0f26b9d0c4 diff --git a/CODING b/CODING index 7ad8170..b1e12c7 100644 --- a/CODING +++ b/CODING @@ -103,3 +103,165 @@ On FreeBSD: In addition, FreeBSD systems require kernel sources and a configured kernel build directory (see section "FreeBSD Notes" in the README file). + +GIT Usage +========= + +*WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* +The Git tree may not always have code which can currently be built. +While every effort is made to keep the head of the tree buildable, +you may at any time find yourself between commits and hence have a tree +which does not build, or worse, causes more serious problems! + +Do not use the Git tree unless you know what you're doing. + +Git checkouts do not include files generated by autoconf. You can +run regen.sh (at the top level) to create these files. You will need +to have autoconf and automake installed on your system. + +Summary +------- + +Browse: http://git.openafs.org/ +Clone: git clone git://git.openafs.org/openafs.git + +Step-by-step +------------ + +1. Obtain the Git software. If you are using a system with a standard + software repository, Git may already be available as a package named + something like git or git-core. Otherwise, go to http://git-scm.com/ + +2. Run the command: + + % git clone git://git.openafs.org/openafs.git + + This will download the full repository and leave a checked-out tree in + a subdirectory of the current directory named openafs. The repository + itself is in the .git subdirectory of that directory. + + WARNING: The repository is approximately 60MiB currently and will only + grow, so it may take some time to download the first time over a slow + network connection. + +3. Generate the additional required files: + + % cd openafs + % ./regen.sh + +The current development series is in the branch named master. The stable +releases are on separate branches named something like +openafs-stable_ with a separate branch for each major stable +release series. Use git branch -a to see a full list of branches. + +OpenAFS uses the Gerrit code review system to review and merge all changes +to OpenAFS. More details are at: + + http://wiki.openafs.org/GitDevelopers/ + +including more detailed Git instructions. + +It's by far preferred to use Gerrit to submit code changes, but if you +can't for whatever reason, you can instead open a bug and submit a patch +that way. Do this by sending mail to openafs-bugs@openafs.org with the +patch attached. But please use Gerrit if you can; patches sent in as bugs +will have to be forwarded to Gerrit by someone else, and it's easier for +everyone if you can enter them into Gerrit yourself. + +Backport policy +------------ +All patches should land on master first, unless the patch fixes a bug +that only exists in the stable branch. + +Once a patch has been accepted into master, anyone can propose +backports to stable branches. + +When cherry-picking a commit from another branch, please append a +"cherry picked from" section in your commit message. You'll also need +a separate Change-ID for Gerrit to recognize this as a separate +change. One workflow to do this: + +1) Use "git cherry-pick -ex" to pick your commits onto another branch. + The -x option will append the appropriate "cherry picked from" + message, and the -e option will open your editor for you to edit + the commit message. +2) In your editor, delete the existing Change-ID line. Save and quit. +3) Run "git commit --amend", saving and quitting again. Git will run + the commit hook and generate a new Change-ID for Gerrit. + +Warnings +======== + +OpenAFS Warning detection +------------------------- + +There's been a concerted effort over the last few years, by many developers, +to reduce the number of warnings in the OpenAFS tree. In an attempt to +prevent warnings from creeping back in, we now have the ability to break the +build when new warnings appear. + +This is only available for systems with gcc 4.2 or later, and is disabled +unless the --enable-checking option is supplied to configure. Because we +can't remove all of the warnings, we permit file by file (and warning by +warning) disabling of specific warnings. The --enable-checking=all prevents +this, and errors for any file containing a warning. + +Disabling warnings +------------------ + +If warnings are unavoidable in a particular part of the build, they may be +disabled in an number of ways. + +You can disable a single warning type in a particular file by using GCC +pragmas. If a warning can be disabled with a pragma, then the switch to use +will be listed in the error message you receive from the compiler. Pragmas +should be wrapped in IGNORE_SOME_GCC_WARNINGS, so that they aren't used +with non-gcc compilers, and can be disabled if desired. For example: + #ifdef IGNORE_SOME_GCC_WARNINGS + # pragma GCC diagnostic warning "-Wold-style-definition" + #endif + +It would appear that when built with -Werror, the llvm clang compiler will +still upgrade warnings that are suppresed in this way to errors. In this case, +the fix is to mark that warning as ignored, but only for clang. For example: + #ifdef IGNORE_SOME_GCC_WARNINGS + # ifdef __clang__ + # pragma GCC diagnostic ignored "-Wdeprecated-declarations" + # else + # pragma GCC diagnostic warning "-Wdeprecated-declarations" + # endif + #endif + +If a pragma isn't available for your particular warning, you will need to +disable all warnings for the file in question. You can do this by supplying +the autoconf macro @CFLAGS_NOERROR@ in the build options for the file. For +example: + lex.yy.o : lex.yy.c y.tab.c + ${CC} -c ${CFLAGS} @CFLAGS_NOERROR@ lex.yy.c + +If you add a new warning inhibition, please also add it to the list below. + +Inhibited warnings +------------------ + +afs/afs_syscall.c : old-style + : strict-proto + : all (ukernel) : syscall pointer issues +afsd/afsd_kernel.c : deprecated : daemon() marked as deprecated on Darwin +auth/ktc.c : all (ukernel) : call_syscall doesn't have a prototype +bozo/bosserver.c : deprecated : daemon() marked as deprecated on Darwin +bucoord/ubik_db_if.c : strict-proto : Ubik_Call +bucoord/commands.c : all : Ubik_Call + : signed vs unsigned for dates +butc/tcudbprocs.c : all : ubik_Call +external/heimdal/hcrypto/validate.c: all: statement with empty body +kauth/admin_tools.c : all : signed vs unsigned for dates +kauth/authclient.c : strict-proto : ubik_Call nonsense +libadmin/kas/afs_kasAdmin.c: all : Ubik_Call nonsense +libadmin/samples/rxstat_query_peer.c : all : util_RPCStatsStateGet types +libadmin/samples/rxstat_query_process.c : all : util_RPCStatsStateGet types +libadmin/test/client.c : all : util_RPCStatsStateGet types +rxkad/ticket5.c : all : v5gen.c has set-but-unused variables +ubik/ubikclient.c : strict-protos : ubik_Call +volser/vol-dump.c : format : afs_sfsize_t +