From 141107622263349e21a90019623e9a88ad01cdee Mon Sep 17 00:00:00 2001 From: Kelvie Wong Date: Wed, 9 Apr 2008 21:11:48 -0700 Subject: [PATCH] Updated the README file with some contributor tips. There's more to write still (especially on the Git section), but this is the developer README. We shouldn't really have any need for a user README at this point anyways. It is an asciidoc document, so I'll probably post the HTML somewhere. I have a feeling this will be split into several documents at some point in the future... --- README | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 143 insertions(+), 42 deletions(-) rewrite README (97%) diff --git a/README b/README dissimilarity index 97% index 8a1ea0e..57f27b5 100644 --- a/README +++ b/README @@ -1,42 +1,143 @@ - ******************** - * BasKet Note Pads * - ******************** - - Purpose: -************ - - This application provide as many baskets as you wish, and you -can drag and drop various objects (text, URLs, images, sounds...) -into its. - Objects can be edited, copied, dragged... So, you can arrange them as -you want ! - It's a DropDrawers clone -(http://www.sigsoftware.com/dropdrawers/index.html) for KDE 3. - - If you want to contact me, please mail me at slaout@linux62.org -(I'm a french guy, if you prefer to speak french to me). - - Project Status: -******************* - - Visit the BasKet Note Pads website at : -http://basket.kde.org/ - You can find screenshots of it at : -http://basket.kde.org/screenshots.php - For project status, please see the TODO file of this project at : -http://basket.kde.org/todo.php - You also can see the project roadmap for near versions planned - features at : -http://basket.kde.org/roadmap.php - See changes log at : -http://basket.kde.org/changelog.php - And finaly, new versions will be announced here : -http://basket.kde.org/news.php - If you want to be noticed of new versions, subscribe to the RSS feed, - available with explanations here: -http://basket.kde.org/rss.php - - Install: -************ - - Please see the INSTALL file. +BasKet Note Pads +================ +Kelvie Wong + +//// +Run this document through asciidoc to read it nicely-formatted in HTML. +//// + +Purpose +------- +(From the original README by Sèbastien) + +This application provides as many baskets as you wish, and you can drag and drop +various objects (text, URLs, images, sounds...) into its. + +Objects can be edited, copied, dragged... So, you can arrange them as you want ! + +It's a DropDrawers clone (http://www.sigsoftware.com/dropdrawers/index.html) for +KDE 3 (soon to be 4, hopefully). + +Project Status +-------------- +Currently, porting to KDE 4 is under way. The KDE 3 version remains unmaintained. + +Developers +----------- +As you may or may not have noticed, there isn't a user's section currently. +If you are reading this, chances are, you are a developer (if I'm wrong email me +;), so most of the developers documentation will go here until we can finalize a +user README after we're done porting. + +Git +~~~ +The porting effort will use Git. The main reason for this is that right now, we +don't have much contact with the main developers, and a bunch of us do not have +SVN access. There are other people who wish to contribute and are in a similar +situation, and so the easiest way to coordinate these efforts is through a +distributed source management system -- Git fills this void nicely, is under +very active development, and is quickly gaining popularity. + +Using Git +~~~~~~~~~ +I'm sure not everyone is familiar with Git. There's plenty of resources about +what commands do what, so here's a just a quick rundown of some Git conventions. + +Don't work on the master branch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Your published `master` branch is the branch other people will be pulling, so +only merge what you are confident with sharing. I generally keep a branch +called `work` in my repository for the main work, and `next` as a branch that's +waiting to be merged into master. + +Basically, keep your `master` clean. Don't try to rewrite history on master +(with git rebase) after it has been published -- if anyone else has pulled from +you, they are going to be in heaps of trouble the next time they try to. +Instead, just add things like revert commits (via `git revert`), or other +amending commits on top of your current `master`. + +Commit messages +^^^^^^^^^^^^^^^ +Feel free to write whatever you want in your own branches, but try to have the +messages that you merge into master follow a specific convention + +It is important to follow this convention because many git tools (such as Github +and the gitweb web interfaces, as well as `git format-patch`, and even `git +log`!) rely on this convention when parsing commit messages. + +In short, the first line of your commit message should be a _very_ short (no +longer than 80 characters) summary of your commit. When creating a patch, it +becomes the subject of the email (in Git, patches are emails). + +Separate it then with two lines (this part's important!), and a detailed +description of the commit. Do not be afraid to write really detailed commit +message (in fact, I'd encourage it! People who want the short version can just +read the first line). + +For example (this is commit `688ab72c`): +---- + Removed all of the whitespace changes from kde4port-svn. (<-- subject line) + + The process to get rid of the whitespace changes was this: (full descrip.) + 1. First ask git to create a diff without whitespace changes + 2. Run a script to go in and reject hunks with non-trivial whitespace + changes (such as multiline whitespace changes and adding whitespace + where there were none before). + 3. Apply the new patch. + 4. Apply the changes between this new HEAD and kde4port-svn onto kde4port-svn + + ... +---- + +Also, good commit messages means we don't have to write changelogs (try it! type +`git shortlog`) + +//// +TODO: More to come.. +//// + +Contributing +~~~~~~~~~~~~ +The first step to contribute is to clone a source repository: + + git clone git://github.com/kelvie/basket.git + +Now you can hack away at it to your hearts content. When you have a series of +patches ready to be merged with my changes, first make sure your master is up to +date with mine: + + git pull git://github.com/kelvie/basket.git master + +(or if you cloned from my repository, just `git pull` will suffice), and ask me +to pull your changes, if you have published them, or use `git format-patch` to +create a series of patches and post them to the mailing list. + +If you want to continue contributing, feel free to fork the main repository on +Github (http://github.com/kelvie/basket/tree/) or repo.or.cz and send pull +requests there. + +Contact +------- +If you have any questions, or would like to contribute (always welcome!) please +send me an email at kelvie@ieee.org, or through the development mailing list at +basket-devel@lists.sourceforge.net. + +I'm usually idle on #basket-devel @ freenode on IRC, but you may catch me on +there. Due to timezone differences, however, it's generally better to email me. + +The BasKet web site (again, unmaintained right now) is at: +http://basket.kde.org/ + + +Building/Installation +---------------------- +It will be a while before the master branch is able to be built without errors, +but to try and do so, follow these steps (this assumes you have the relevant +kde4 development libraries and CMake): + +---- +mkdir build +cd build +cmake .. +make +---- -- 2.11.4.GIT