Developer Infos

From Netatalk Wiki
Jump to: navigation, search
(Debugging process crashes)
 
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 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 143: Line 175:
  
 
Developers doing releases are expected to have a working understanding of the ABI checking infrastructure and must use the --enable-developer configure option.
 
Developers doing releases are expected to have a working understanding of the ABI checking infrastructure and must use the --enable-developer configure option.
 
* Create release branch from "develop" branch
 
  $ git checkout -b release-3.0beta2
 
  Switched to a new branch 'release-3.0beta2'
 
  
 
* Bump VERSION
 
* 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
 
* Re-run configure so the VERSION bump gets passed to the build system
Line 199: Line 233:
  
 
* Run make distcheck, fix any errors
 
* Run make distcheck, fix any errors
No errors? Great, time to release:
 
  
* Switch to 3.0 release branch "master"
+
* Regenerate manpages from XML sources
   $ git checkout master
+
   $ make html
   $ git merge release-3.0beta2
+
   $ git commit -a -m "Generate manpages from XML"
   ...
+
 
   $ git push SOURCEFORGE-GIT-REPO master
+
* 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 tag TAG
 
   $ git push SOURCEFORGE-GIT-REPO TAG
 
   $ git push SOURCEFORGE-GIT-REPO TAG
Line 211: Line 250:
 
   $ make dist-bzip2
 
   $ make dist-bzip2
  
* Merge changes from release branch back into develop
+
* Upload updates online manual:
   $ git checkout develop
+
   $ cd doc/manual/
   $ git merge release-3.0beta2
+
   doc/manual/ $ USER=netatalk-sourceforge-adminuser make html-upload
  $ git branch -d release-3.0beta2
+
  
* Reset VERSION to eg 3.0dev
+
* Reset VERSION to eg 3.0.8dev
  
 
== FAQ ==
 
== FAQ ==

Latest revision as of 13:42, 18 June 2016

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox