docs/customize-outside-adk.txt

   1 // -*- mode:doc -*- ;
   2
   3 [[outside-adk-custom]]
   4 Keeping customizations outside OpenADK
   5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   6
   7 The OpenADK project recommends and encourages upstreaming to the
   8 official OpenADK version the packages and board support that are
   9 written by developers. However, it is sometimes not possible or
  10 desirable because some of these packages or board support are highly
  11 specific or proprietary.
  12
  13 In this case, OpenADK users are offered following choice using
  14 here own git repository.
  15
  16 * Initialize your project
  17
  18 Personalize your Git environment via:
  19
  20 ---------------------
  21  $ git config --global user.name "Waldemar Brodkorb"
  22  $ git config --global user.email wbx@openadk.org
  23 ---------------------
  24
  25 Get the latest version of OpenADK via anonymous git:
  26
  27 ---------------------
  28  $ git clone --bare git://openadk.org/git/openadk myadk.git
  29 ---------------------
  30
  31 Use git-daemon to make the repository public to your developers. After that clone your new shared project repository:
  32
  33 ---------------------
  34  $ git clone git+ssh://myserver.com/git/myadk.git
  35  $ cd myadk
  36 ---------------------
  37
  38 Configure OpenADK remote git repository:
  39
  40 ---------------------
  41  $ git remote add openadk git://openadk.org/git/openadk
  42 ---------------------
  43
  44 * Create your firmware
  45
  46 Now you can either start with the latest version or use some older version:
  47
  48 ---------------------
  49  $ git checkout -b stable_1_0 $sha1
  50 ---------------------
  51 You can find $sha1 via git log. $sha1 is the hash after the keyword “commit”.
  52
  53 Now build a firmware image for your target and test it. Fix bugs in the build
  54 environment or add new stuff. You can use the “extra” directory to add local
  55 unpackaged binaries and/or configuration files to overwrite packaged stuff.
  56
  57 Check your uncommitted changes:
  58
  59 ---------------------
  60  $ git status
  61  $ git diff --cached
  62  $ git diff
  63 ---------------------
  64
  65 Commit your git-added changes:
  66
  67 ---------------------
  68  $ git commit
  69 ---------------------
  70 Or just commit all changes:
  71
  72 ---------------------
  73  $ git commit -a
  74 ---------------------
  75 It is a good style to make a lot of small atomic commits.
  76
  77 Push your changes back to your git repository.
  78 For new local branches:
  79
  80 ---------------------
  81  $ git push origin stable_1_0
  82 ---------------------
  83
  84 Or in regulary usage via:
  85 ---------------------
  86  $ git push
  87 ---------------------
  88
  89 * Working together with OpenADK
  90
  91 You can generate patches from all your changes against the remote master:
  92
  93 ---------------------
  94  $ git format-patch -s origin
  95 ---------------------
  96
  97 Send all relevant patches to OpenADK author via eMail.
  98
  99 Update your master with changes from OpenADK:
 100
 101 ---------------------
 102  $ git checkout master
 103  $ git pull openadk master
 104 ---------------------
 105
 106 If you want you can merge all changes to your branch:
 107
 108 ---------------------
 109  $ git checkout stable_1_0
 110  $ git merge master
 111 ---------------------
 112
 113 Or just cherry-pick some of the commits:
 114
 115 ---------------------
 116  $ git cherry-pick $sha1
 117 ---------------------
 118
 119 * Releasing
 120
 121 Tag your tested stable branch:
 122
 123 ---------------------
 124  $ git tag -a stable_1.0
 125 ---------------------
 126 Push your tag to your repository:
 127
 128 ---------------------
 129  $ git push origin stable_1.0
 130 ---------------------
 131
 132 Checkout your tag and build your firmware:
 133
 134 ---------------------
 135  $ git clone git+ssh://myserver.com/git/myadk.git mytag
 136  $ cd mytag
 137  $ git checkout stable_1.0
 138 ---------------------
 139
 140 * Deleting unused branches
 141
 142 Deleting branches remotely:
 143
 144 ---------------------
 145  $ git branch -r
 146  $ git push origin :branchname
 147 ---------------------
 148
 149 Deleting branches locally:
 150
 151 ---------------------
 152  $ git branch
 153  $ git branch -D branchname
 154 ---------------------