README

   1 BasKet Note Pads
   2 ================
   3 Kelvie Wong <kelvie@ieee.org>
   4
   5 ////
   6 Run this document through asciidoc to read it nicely-formatted in HTML.
   7 ////
   8
   9 Purpose
  10 -------
  11 (From the original README by Sèbastien)
  12
  13 This application provides as many baskets as you wish, and you can drag and drop
  14 various objects (text, URLs, images, sounds...)  into its.
  15
  16 Objects can be edited, copied, dragged... So, you can arrange them as you want !
  17
  18 It's a DropDrawers clone (http://www.sigsoftware.com/dropdrawers/index.html) for
  19 KDE 3 (soon to be 4, hopefully).
  20
  21 Project Status
  22 --------------
  23 Currently, porting to KDE 4 is under way.  The KDE 3 version remains unmaintained.
  24
  25 Developers
  26 -----------
  27 As you may or may not have noticed, there isn't a user's section currently.
  28 If you are reading this, chances are, you are a developer (if I'm wrong email me
  29 ;), so most of the developers documentation will go here until we can finalize a
  30 user README after we're done porting.
  31
  32 Git
  33 ~~~
  34 The porting effort will use Git.  The main reason for this is that right now, we
  35 don't have much contact with the main developers, and a bunch of us do not have
  36 SVN access.  There are other people who wish to contribute and are in a similar
  37 situation, and so the easiest way to coordinate these efforts is through a
  38 distributed source management system -- Git fills this void nicely, is under
  39 very active development, and is quickly gaining popularity.
  40
  41 Using Git
  42 ~~~~~~~~~
  43 I'm sure not everyone is familiar with Git.  There's plenty of resources about
  44 what commands do what, so here's a just a quick rundown of some Git conventions.
  45
  46 Don't work on the master branch
  47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  48 Your published `master` branch is the branch other people will be pulling, so
  49 only merge what you are confident with sharing.  I generally keep a branch
  50 called `work` in my repository for the main work, and `next` as a branch that's
  51 waiting to be merged into master.
  52
  53 Basically, keep your `master` clean.  Don't try to rewrite history on master
  54 (with git rebase) after it has been published -- if anyone else has pulled from
  55 you, they are going to be in heaps of trouble the next time they try to.
  56 Instead, just add things like revert commits (via `git revert`), or other
  57 amending commits on top of your current `master`.
  58
  59 Commit messages
  60 ^^^^^^^^^^^^^^^
  61 Feel free to write whatever you want in your own branches, but try to have the
  62 messages that you merge into master follow a specific convention
  63
  64 It is important to follow this convention because many git tools (such as Github
  65 and the gitweb web interfaces, as well as `git format-patch`, and even `git
  66 log`!)  rely on this convention when parsing commit messages.
  67
  68 In short, the first line of your commit message should be a _very_ short (no
  69 longer than 80 characters) summary of your commit.  When creating a patch, it
  70 becomes the subject of the email (in Git, patches are emails).
  71
  72 Separate it then with two lines (this part's important!), and a detailed
  73 description of the commit.  Do not be afraid to write really detailed commit
  74 message (in fact, I'd encourage it! People who want the short version can just
  75 read the first line).
  76
  77 For example (this is commit `688ab72c`):
  78 ----
  79     Removed all of the whitespace changes from kde4port-svn. (<-- subject line)
  80
  81     The process to get rid of the whitespace changes was this: (full descrip.)
  82     1. First ask git to create a diff without whitespace changes
  83     2. Run a script to go in and reject hunks with non-trivial whitespace
  84        changes (such as multiline whitespace changes and adding whitespace
  85        where there were none before).
  86     3. Apply the new patch.
  87     4. Apply the changes between this new HEAD and kde4port-svn onto kde4port-svn
  88
  89     ...
  90 ----
  91
  92 Also, good commit messages means we don't have to write changelogs (try it! type
  93 `git shortlog`)
  94
  95 ////
  96 TODO: More to come..
  97 ////
  98
  99 Contributing
 100 ~~~~~~~~~~~~
 101 The first step to contribute is to clone a source repository:
 102
 103   git clone git://github.com/kelvie/basket.git
 104
 105 Now you can hack away at it to your hearts content.  When you have a series of
 106 patches ready to be merged with my changes, first make sure your master is up to
 107 date with mine:
 108
 109   git pull git://github.com/kelvie/basket.git master
 110
 111 (or if you cloned from my repository, just `git pull` will suffice), and ask me
 112 to pull your changes, if you have published them, or use `git format-patch` to
 113 create a series of patches and post them to the mailing list.
 114
 115 If you want to continue contributing, feel free to fork the main repository on
 116 Github (http://github.com/kelvie/basket/tree/) or repo.or.cz and send pull
 117 requests there.
 118
 119 Contact
 120 -------
 121 If you have any questions, or would like to contribute (always welcome!) please
 122 send me an email at kelvie@ieee.org, or through the development mailing list at
 123 basket-devel@lists.sourceforge.net.
 124
 125 I'm usually idle on #basket-devel @ freenode on IRC, but you may catch me on
 126 there.  Due to timezone differences, however, it's generally better to email me.
 127
 128 The BasKet web site (again, unmaintained right now) is at:
 129 http://basket.kde.org/
 130
 131
 132 Building/Installation
 133 ----------------------
 134 It will be a while before the master branch is able to be built without errors,
 135 but to try and do so, follow these steps (this assumes you have the relevant
 136 kde4 development libraries and CMake):
 137
 138 ----
 139 mkdir build
 140 cd build
 141 cmake ..
 142 make
 143 ----