Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match_all(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 717

Warning: Invalid argument supplied for foreach() in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 718

Warning: preg_replace(): Compilation failed: group name must start with a non-digit at offset 4 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 722

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739

Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739
Developer Infos - Netatalk Wiki

Developer Infos


Warning: preg_match(): Compilation failed: group name must start with a non-digit at offset 8 in /home/project-web/netatalk/htdocs/wiki/includes/MagicWord.php on line 739
From Netatalk Wiki
Jump to: navigation, search
m (moved Git to Developer Infos)
 
Line 2: Line 2:
  
 
Netatalk source code is now hosted in a shared git repository to which only Netatalk Team members are allowed to push into.
 
Netatalk source code is now hosted in a shared git repository to which only Netatalk Team members are allowed to push into.
 +
 +
== Links to Developer Ressources ==
 +
* [https://developer.apple.com/library/mac/#documentation/Networking/Conceptual/AFP/Introduction/Introduction.html AFP Programming Guide]
 +
* [https://developer.apple.com/library/mac/#documentation/Networking/Reference/AFP_Reference/Reference/reference.html AFP Reference Guide]
 +
* [http://developer.apple.com/legacy/mac/library/documentation/mac/toolbox/Toolbox-463.html Inside Macintosh: Macintosh Toolbox Essentials Chapter 7 - Finder Interface]
 +
* [http://developer.apple.com/legacy/mac/library/documentation/Carbon/Reference/Finder_Interface/Reference/reference.html Finder Interface Reference]
 +
* [http://developer.apple.com/mac/library/technotes/tn/tn1150.html#FinderInfo Technical Note TN1150  HFS Plus Volume Format]
 +
* [http://www.opensource.apple.com/source/CarbonHeaders/CarbonHeaders-9A581/Finder.h CarbonHeaders source]
 +
* [http://www.opensource.apple.com/source/xnu/xnu-1486.2.11/bsd/vfs/vfs_xattr.c Mac OS X 10.6.2 source]
 +
* [http://users.phg-online.de/tk/netatalk/doc/Apple/v1/ AppleSingle and AppleDouble v1 format internals]
 +
* [[Media:AppleSingle_AppleDouble.pdf|AppleSingle/AppleDouble Formats for Foreign Files Developer's Note (version2)]]
  
 
== Git Installation ==
 
== Git Installation ==
Line 12: Line 23:
 
Note that under Debian or Ubuntu, git is distributed in the git-core package.  The git package contains the "GNU Interactive Tools".  
 
Note that under Debian or Ubuntu, git is distributed in the git-core package.  The git package contains the "GNU Interactive Tools".  
  
== Main Netatalk Branches ==
+
== Branching model ==
 +
 
 +
* the "master" branch is where development on new features is taking place
 +
* branches named "branch-netatalk-x.y" for stable releases
 +
* currently stable release branch ''branch-netatalk-3-1''
 +
* commits go to master (after a review, more on that below) 
 +
* commits can only go into a release branch if a bugreport exists
 +
* the bugreport must be referenced in the commit message
 +
* no branch merges
 +
 
 +
== Review process ==
 +
 
 +
We now require formal review of all patches.
 +
 
 +
The author of patch should add a signed-off tag and the reviewer adds a reviewed-by tag. Very formal, but it encourages better coding and documentation.
 +
 
 +
This means every commit in master should have been reviewed by two team members (if the author is a team member, only one review by another team member needed).
 +
 
 +
This is the same process used in [https://wiki.samba.org/index.php/CodeReview Samba]
 +
 
 +
== Commit messages ==
 +
 
 +
Commit messages should have a short, descriptive first summary line that begins with the affected component, eg
 +
 
 +
  afpd: new options "force user" and "force group"
 +
 
 +
This is helpful when browing a git log in oneline mode.
 +
 
 +
Then the commit message should explain what the change is about, the more, the better.
  
Development now uses a branching workflow adopted from [http://nvie.com/posts/a-successful-git-branching-model/ A successful Git branching model].
+
At the end the author adds his signed-off tag.
* the "master" branch is for creating releases of the current release series (currently Netatalk 3.x, 28.3.2012), never commit changes on this branch(!)
+
* the "develop" branch is where development on 3.x is happening
+
* feature branches can be used to develop new features for the upcoming or a distant future release. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into "develop". Feature branches often exist in developer repos only, but may be pushed to the central git repo for collaboration
+
* in addition to [http://nvie.com/posts/a-successful-git-branching-model/ A successful Git branching model] we use branches named "product-x.y" for older versions still in stable maintenance mode (currently "product-2-2" for Netatalk 2.2.z)
+
  
 
== Basic Netatalk Git ==
 
== Basic Netatalk Git ==
Line 30: Line 65:
 
Next, clone the repository:
 
Next, clone the repository:
 
   $ git clone git://netatalk.git.sourceforge.net/gitroot/netatalk/netatalk
 
   $ git clone git://netatalk.git.sourceforge.net/gitroot/netatalk/netatalk
   Initialized empty Git repository in /home/ralph/test/.git/
+
   Initialized empty Git repository in /home/frank/test/.git/
 
   remote: Counting objects: 31503, done.
 
   remote: Counting objects: 31503, done.
 
   remote: Compressing objects: 100% (11427/11427), done.
 
   remote: Compressing objects: 100% (11427/11427), done.
Line 46: Line 81:
 
   origin/branch-netatalk-2-0
 
   origin/branch-netatalk-2-0
 
   origin/branch-netatalk-2-1
 
   origin/branch-netatalk-2-1
   origin/develop
+
   origin/branch-netatalk-2-2
 +
  origin/branch-netatalk-3-0
 +
  origin/branch-netatalk-3-1
 
   origin/master
 
   origin/master
  origin/product-2-2
 
 
</pre>
 
</pre>
  
 
Creating your own working branch from master:
 
Creating your own working branch from master:
   $ git checkout -b my_branch origin/develop
+
   $ git checkout -b my_branch
 
   Branch my_branch set up to track remote branch refs/remotes/origin/develop.
 
   Branch my_branch set up to track remote branch refs/remotes/origin/develop.
 
   Switched to a new branch "my_branch"
 
   Switched to a new branch "my_branch"
Line 88: Line 124:
  
 
Now fetch the remote branch history:
 
Now fetch the remote branch history:
   $ git fetch  
+
   $ git fetch
 
+
Merging remote branch changes:
+
  $ git merge origin/develop
+
  ...
+
  
 
To present your patchset properly to other developers, please rebase your patches against the branch you are developing against:
 
To present your patchset properly to other developers, please rebase your patches against the branch you are developing against:
   $ git rebase origin/develop
+
   $ git rebase origin/master
Obviously replace "origin/develop" by whatever branch you are developing against. If you have created a mess in your local patch queue, "git rebase -i" might help you out.
+
Obviously replace "origin/master" by whatever branch you are developing against. If you have created a mess in your local patch queue, "git rebase -i" might help you out.
  
 
== Creating patches ==
 
== Creating patches ==
Line 115: Line 147:
  
 
   $ git format-patch --stdout origin/develop > develop-featureX-01.patches.txt
 
   $ git format-patch --stdout origin/develop > develop-featureX-01.patches.txt
 +
 +
== Debugging process crashes ==
 +
 +
We need a stack-backtrace (SBT) from a corefile with debugging symbols.
 +
 +
* Compile Netatalk with debugging symbols and without optimizations, eg for gcc
 +
  CFLAGS="-g -O0" ./configure ... && make && make install
 +
 +
* Enable global corefile generation ([http://www.google.com/search?q=linux+enable+core+dump Linux], [http://www.google.com/search?q=man+coreadm Solaris])
 +
* Enable corefile generation for Netatalk by adding
 +
  ulimit -c unlimited
 +
at the beginning of the Netatalk start script and restart Netatalk.
 +
* Reproduce issue
 +
* Get SBT (example for a crash of afpd and gdb):
 +
  $ gdb path/to/afpd path/to/corefile
 +
  (gdb) bt full
 +
  ...
 +
  (gdb) exit
  
 
== ABI checking ==
 
== ABI checking ==
  
Since libatalk is now a shared library the autotools build system has been extended to do some ABI checking.
+
Since libatalk is now a shared library the autotools build system has been extended to do some ABI checking. A helper script '''abigen.sh''' is used to generate a symbol file containing all exported symbols of the dynamic libatalk library. These symbol files are named '''''libatalk-VERSION.abi''''' and are stored inside the libatalk source directory.
 +
 
 +
Every time make runs inside libatalk a symbol file '''libatalk.abi.tmp''' is autogenerated and checked against the current copy of the file matching the configured VERSION (as contained in the file VERSION). If there are any differences found, make aborts and the developer must update the symbol file and '''''libatalk/Makefile.am''''' library version info accordingly.
 +
 
 +
== Making a release ==
 +
 
 +
Developers doing releases are expected to have a working understanding of the ABI checking infrastructure and must use the --enable-developer configure option.
 +
 
 +
* Bump VERSION
 +
  $ vi VERSION
 +
  $ git commit -a -m "Bump version to x.x.x"
 +
 
 +
* Update NEWS as necessary:
 +
  $ vi NEWS
 +
  $ git commit -a -m "Update NEWS"
 +
 
 +
* Re-run configure so the VERSION bump gets passed to the build system
 +
  $ ./configure ...
 +
 
 +
* Run make, this will create library ABI files
 +
  $ make clean && make
 +
  ...
 +
  make[3]: Entering directory `/home/frank/netatalk/develop/libatalk'
 +
  **********************************************************************************************************
 +
                                  created ABI file libatalk-3.0beta2.abi
 +
      check https://sourceforge.net/apps/mediawiki/netatalk/index.php?title=Developer_Infos#ABI_checking
 +
  **********************************************************************************************************
 +
  make[3]: *** [all-local] Error 1
 +
  ...
 +
  $ git status
 +
  # On branch release-3.0beta2
 +
  # Untracked files:
 +
  #  (use "git add <file>..." to include in what will be committed)
 +
  #
 +
  # libatalk/libatalk-3.0beta2.abi
 +
  nothing added to commit but untracked files present (use "git add" to track)
 +
 
 +
* Add ABI file to git and appropriate Makefile.am (eg libatatalk/Makefile.am for libatalk) ABI files
 +
  $ git add libatalk/libatalk-3.0beta2.abi
 +
  $ git commit -m "Import libatalk-3.0-beta2 ABI file"
 +
  $ emacs libatalk/Makefile.am
 +
  ...
 +
  $ ./bootstrap && ./configure ... (ensure the Makefile.am change takes effect) && make
 +
This make run should now pass without error.
 +
 
 +
* Compare the ABI file to the previous version, verify VERSION_INFO, update Makefile.am version history
 +
Update VERSION_INFO as necessary, update libatalk/Makefile.am version history. Note that VERSION_INFO info might already have been updated by the ongoing ABI checks by a developer when working on develop.
 +
  $ git diff
 +
  @@ -28,6 +26,7 @@ VERSION_INFO = 1:0:0
 +
  #  3.0.0-alpha2    0:0:0
 +
  #  3.0.0-alpha3    0:0:0
 +
  #  3.0.0-beta1    0:0:0
 +
  +#  3.0.0-beta2    1:0:0
 +
 
 +
  SUBDIRS = acl adouble bstring compat cnid dsi iniparser tdb util unicode vfs
 +
 
 +
  @@ -85,3 +84,4 @@ all-local: .libs/libatalk.so
 +
 
 +
  EXTRA_DIST = \
 +
          libatalk-3.0beta1.abi \
 +
  +      libatalk-3.0beta2.abi
 +
 
 +
If you have to update VERSION_INFO again, commit the change, rebootstrap and configure.
 +
 
 +
* Run make distcheck, fix any errors
 +
 
 +
* Regenerate manpages from XML sources
 +
  $ make html
 +
  $ git commit -a -m "Generate manpages from XML"
 +
 
 +
* Update and upload release notes:
 +
  $ cd doc/
 +
  doc/ $ vi www/ReleaseNotes
 +
  doc/ $ git commit -a -m "Update release notes"
 +
  doc/ $ USER=netatalk-sourceforge-adminuser make upload-release-notes
 +
 
 +
* Tag, release and roll tarballs
 +
  $ git tag TAG
 +
  $ git push SOURCEFORGE-GIT-REPO TAG
 +
  $ make dist
 +
  $ make dist-bzip2
 +
 
 +
* Upload updates online manual:
 +
  $ cd doc/manual/
 +
  doc/manual/ $ USER=netatalk-sourceforge-adminuser make html-upload
 +
 
 +
* Reset VERSION to eg 3.0.8dev
  
 
== FAQ ==
 
== FAQ ==
Line 142: Line 278:
  
 
Rebase works best when you use it for local branches that are never pushed to a public repository, see [http://git.or.cz/gitwiki/GitFaq#head-c1dc263aca199d347f28872249e6c1f5d519a2df Why won't "git push" work after I rebased a branch?].
 
Rebase works best when you use it for local branches that are never pushed to a public repository, see [http://git.or.cz/gitwiki/GitFaq#head-c1dc263aca199d347f28872249e6c1f5d519a2df Why won't "git push" work after I rebased a branch?].
 +
 +
[[Category:Mainpage]]

Latest revision as of 13:42, 18 June 2016

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox