Difference between revisions of "Overlay:Flora"

Revision as of 07:37, 4 August 2011

What is flora

flora is the funtoo overlay for User Contribution to funtoo.

Some of you may ask "Why they call it flora?"

For that have a view at the definition for flora:

1. Plants considered as a group, especially the plants of a particular country, region, or time.
2. A treatise describing the plants of a region or time.
3. The bacteria and other microorganisms that normally inhabit a bodily organ or part: intestinal flora.

We hope that only the first two definitions would be suitable for submitted ebuilds :)

How to work with ...

... flora

Core Team

Core Members can directly push to flora, they have the appropriate rights, just do

cd <your dir for overlays>
git clone git@github.com:funtoo/flora.git

Now you will be able to push to and pull from flora. For development in git I would all members advice to use git-flow, since we get a clean structure without any stuff of development left in the later overlay that way. ;) See the Git Guide and and the flora#... git-flow for it.

User Contribution

For normal users that like to contribute it is a bit more complicated but we will now walk through it with you, helping you to do so.

First you have to have a git-hub account, for that you can follow our Git Guide to get one. If you have already one keep on here, if not get one first.

Since you should have a git-hub account now, go visit https://github.com/funtoo/flora and use the fork button on the top to fork the repository to your own account so you can push to it later.

Now you should create a directory to contain the local copy of the overlay repository on your local disk. Let's say you use /root/.git for it, but you may use what ever you want to.

cd /root/.git
git clone git@github.com:<your github username>/flora.git

Now you are nearly ready to contribute. You have flora cloned to /root/.git/flora now and we will go in it and make the necessary changes so we can work with it like we would. Read on in flora#... git-flow.

... git-flow

Since this is a very helpful tool, you should just emerge it and also the git-flow-completion package, as it will support you in your work.

# emerge -avt gitflow git-flow-completion

When it is installed, move to your flora overlay and initialize the git-flow for it. In the following we suppose that you used /root/.git/flora for your overlay.

# cd /root/.git/flora
# git-flow init
No branches exist yet. Base branches must be created now.
Branch name for prodution releases: [master] <ENTER>
Branch name for "next release" development: [develop] <ENTER>

Ho to name your supporting branch prefixes?
Feature branches? [feature/] <ENTER>
Release branches? [release/] <ENTER>
Hotfix branches? [hotfix/] <ENTER>
Support branches? [support/] <ENTER>
Version tag prefix? [] <ENTER>
#

Your main work will now be done in the develop branch. When you want to add a feature or do a hotfix you just do

# git-flow feature start <name of feature>
(Edit of feature)

You can at any time switch to the development branch again with

# git checkout develop

To see which features you have open you can use

# git-flow feature [list]

If your feature is finished do

# git-flow feature finish <name>

For a hotfix to any of your ebuilds you use

# git-flow hotfix start <version>

Now you can hotfix the ebuild and do a simple

# git-flow hotfix finish <version>

Now that we now how to add features, do hotfixes and support work, we still need to know how to do a release. This is done like that:

# git add <directory or file>
# git commit
(Now your editor will appear if you followed our Git Guide)
# git-flow release start <name>
Switched to a new branch 'release/<name>'

Summary of actions
- A new branch 'release/<name>' was created, based on 'develop'
- You are now on branch 'release/<name>'

Follow-up actions:
- Bump the version number now!
- Start committing last-minute fixes in preparing your release
- When done, run:

     git-flow release finish <name>
#
(Do what is noted above if needed)
# git-flow release finish <name>
Switched to branch 'master'
Merge made by recursive
 X files changed, X insertions(+), X deletions(-)
 create mode aaaaaa README
Deleted branch release/<name> (was <githash>)

(your editor will come up so you cann give a release note, save and close your editor then.)

Summary of actions:
- Latest objects have been fetched from 'origin'
- Release branch has been merged into 'master'
- The release was tagged '<name>'
- Release branch has been back-merged into 'develop'
- Release branch 'release/<name>' has been deleted

# 
(as we are now on the master branch we can do the push and go back to development branch
# git push
# git checkout develop

Now you should have an overview of how we like to work in flora and keep a clean structure in it.

This workflow model will then look like the following graph:

Notify us about your commit

To make us aware that you commited something go again to your github.com account and give us a Pull Request, so we can have a short review of your push and include it that way into the main tree. If you started working on an ebuild please let us know that you are responsible for it by adding your data to ebuild Maintainer list

A Days work with flora

At that point you should should already have a copy of flora and you should be firm with the git-flow extension for github... :) fine so we are ready to start our dayly work flora now.

First we need to keep in sync with the mainstream flora repository, that could be done really easy...

first add a upstream branch to your flora clone:

then you can keep updated with flora via the following commandsequence:

That work should always be done before you start working in flora, so for your help you could also write a short shell script for it that could do the job for you, or copy our script here and place it in /root/bin/floraupdate

#!/bin/sh
cd <path-to-your-flora-clone>
git fetch upstream
git merge upstream/master
git merge master/develop

So that you would now like to start a new ebuild for a package you want to add to flora and so to funtoo make sure you are on the develop branch. You can check this with

it tells you with the asterisk your currently active working branch and if it isn't "develop" you switch there with:

now that you are in the right branch, you can start your work as your tree is up-to-date. :)

Adding a new ebuild

for adding a new ebuild you do

you will be now in the "feature/<name-of-ebuild>" branch, but be aware git-flow doesn't like whitespaces in the name-of-ebuild name.

No you can work on the feature, let it be called ebuild in that context, if you finished with doing all the modifications of the ebuild you are going to include into flora, finish your work with a

so now you can start adding a new ebuild with the same above procedure, you can always do

to go back to your develop-branch without closing the feature-branch and that way you will not have included the feature-branch into development :)

You can so have several ebuilds developed next to each other without having to worry about having your develop-branch compromised, if you want to delete a branch as the ebuild has been added by someone else already do

where in the case above the <branch-name> would be "feature/<name-of-ebuild>". So far you are now able to work on the develop branch. and commit a new ebuild into your development branch :)

Doing a hotfix

Now you got informed by users that there is a problem with your ebuild, and you know how to quickly solve it we do a hotfix for it, so you start now a hotfix for it with the following command:

Now you add all the stuff you need to fix the ebuild and then you are ready to publish your hotfix for it.

Now your Hotfix has been publish next is to push the hotfix for doing so read flora#Submitting your relase

Doing a release of your ebuild

Now that you are aware of how to add a new ebuild to your local fork of flora you need to make a relase out of it. it is as easy as doing the preparations itself :)

just be ready to make the release

now you are able to the final release corrections for your release so if you found out that there had still been a problem with your ebuild fix it now. if done do

Now get ready to submit all your changes :)

Submitting your release

this part is the easiest as you don't have to do anything for it

That was it. :) Now make us aware of your additions.

Make us aware of your additions

To make us aware of your additions to flora visit your flora overlay under http://github.com/<your-username>/flora.

There you will find a link called Pull Request, have a look at the top on the following screenshot red Circle :)

After pressing the Pull Request button, you are presented with a preview page where you can enter a title and optional description, see exactly what commits will be included when the pull request is sent, and also see who the pull request will be sent to:

Markdown is supported in the description, so you can embed images or use preformatted text blocks.

Switch to the Commits tab to ensure that the correct set of changes is being sent:

Review the diff of all changes by switching to the Files Changed tab:

So now we are aware of your request and can decide how to handle it, mostly it will be included...

Special Stuff in flora

The following content is also available in "flora/profiles/doc/README"

We added 3 folders to flora/profiles called 'package.mask', 'sets' and 'docs'. These folders are there for a special reason and you should be aware of some rules that need to be followed to let us all live peaceful together.

What are the folders there for?

• flora/profiles/docs
  This folder is there for docs if you need a special setup, like using sets for unmasking special stuff.
• flora/profiles/sets
  This folder is there do define a special unmasking set or useflagset for packages you sent to flora, your sets should get there into subfolders.
• flora/profiles/package.mask
  And finaly as you might already thought here you can set a special mask for packages you submitted. Please don't mask packages in here you haven't submitted, if you do so it could result in enourmous trouble for the devs and that is something we would like to avoid.

rules for flora/profiles/docs

In 'flora/profiles/docs' you will insert docs for special stuff like unmasking your ebuilds if you masked them. Please try to avoid a mask of ebuilds but sometimes it is not possible to avoid it we know. Your doc should be named README.<package> so users can easyly find it.

rules for flora/profiles/sets

In 'flora/profiles/sets' you will insert sets to unmask several ebuilds at a time, like if you commit 5 packages that are needed to build and for testing purpose you decide to mask them first, you can define a set here to unmask them. These sets go in subfolders of 'flora/profiles/sets' so you would result in a structure like

flora/profiles/sets/<packagename>/<packagename>.unmask

The content of such an unmask file could look like that:

   
#############################################################
# unmask for <packagename>
#############################################################
=<category>/<packagename>-<version> 
...

in the docs you should then tell the user to link

'portage-path/profiles/sets/<packagename>/<packagename>.unmask'

into /etc/portage/package.unmask/<packagename> or add the stuff of the file to /etc/portage/package.unmask depending on their setup. :)

rules for flora/profiles/packages.mask

Here we use the strongest rules that need to be followed!

• Don't mask any core packages! You are only allowed to mask packages you are responsable for. Also if you try to commit core packages we could get angry, so please talk about these packages first with us. We don't bite but react angry if you try to kill our core :)
• Try to avoid a mask of packages if possible! :)
• Mask reasons have to be significant and should be explained why. Remember you are responsable for the mask no Core Team member will remove them!
• Users that didn't set the mask are not allowed to remove it! Only submitter is allowed to do so! :)

Four simple rules that you must follow so we don't get into trouble :)

For 'flora/profiles/packages.mask' we advice the following setup:

flora/profiles/packages.mask/funtoo-flora-<username>

so we don't have to care about 3 guys editing the same file and giving us headaches when we merge :)

if you follow these few rules we are sure we all make it up in a good manner here and live next to each other in peace.