Difference between revisions of "Overlay:Flora"

Revision as of 23:03, 2 December 2012

What is flora

flora is Funtoo's overlay for user-contributed ebuilds. Why is it called flora? Let's have a look at the definition of flora.

1. A group of plants, especially the indigenous plants of a particular time or region.
2. A book or treatise describing the plants of a particular region or time.
3. Bacterial organisms, like those that naturally inhabit a bodily organ or appendage, e.g. intestinal flora.

We hope that only the first two definitions will be taken into account when submitting ebuilds to flora. We try to uphold Funtoo's high standards in ebuilds submitted to flora. It would be unrealistic to expect users not to make mistakes, however. As we are all humans (hopefully) and all humans make mistakes, just give us a call if you make a mistake so that we can take care of it as soon as possible. :)

The following image gives you an overview on how the Funtoo Portage tree and especially flora is structured:

How to...

... work with flora

Core Team

Core Members can push directly to flora as they already have the appropriate rights. Just do:

cd <your dir for overlays>
git clone repos@git.funtoo.org:flora.git

You will now be able to push/pull to and from flora. For development in git I would advise all members to use git-flow, since it ensures a clean working copy without any development stuff left over and pushed to the overlay. See the Git Guide and flora#... git-flow for more information on git-flow.

merging in Upstream User Contributions

The workflow is splitted into some easy steps just follow the next instructions:

• Add the forks to our flora clone:
  The general syntax to add a remote clone for flora is:

  git remote add <username> git://github.com/<username>/flora.git

  so far the following forks are known and can be added if you copy the context:

  git remote add timoahummel git://github.com/timoahummel/flora.git
  git remote add leprosys git://github.com/leprosys/flora.git
  git remote add init6 git://github.com/init6/flora.git
  git remote add tarsius git://github.com/tarsius/flora.git
  git remote add tobert git://github.com/tobert/flora.git
  git remote add stasikos git://github.com/stasikos/flora.git
  git remote add trq git://github.com/trq/flora.git
  git remote add keenblade git://github.com/keenblade/flora.git
  git remote add edwtjo git://github.com/edwtjo/flora.git
  git remote add strowi git://github.com/strowi/flora.git
  git remote add ipalaus git://github.com/ipalaus/flora.git
  git remote add N4th4 git://github.com/N4th4/flora.git
  git remote add jmarcet git://github.com/jmarcet/flora.git
  git remote add drzayer git://github.com/drzayer/flora.git
  git remote add cvantassle git://github.com/cvantassle/flora.git
  git remote add wishstudio git://github.com/wishstudio/flora.git
  git remote add Saint0fCloud git://github.com/Saint0fCloud/flora.git
  git remote add The-Judge git://github.com/The-Judge/flora.git
  git remote add kpacheco git://github.com/kpacheco/flora.git
  git remote add modethirteen git://github.com/modethirteen/flora.git
  git remote add sandikata git://github.com/sandikata/flora.git
  git remote add synchris git://github.com/synchris/flora.git
  git remote add vadmeste git://github.com/vadmeste/flora.git
  git remote add rh1 git://github.com/rh1/flora.git
  git remote add just1602 git://github.com/just1602/flora.git
  git remote add mozgwar git://github.com/mozgwar/flora.git
  git remote add rem7 git://github.com/rem7/flora.git
  git remote add akiress git://github.com/akiress/flora.git
  git remote add ereslibre git://github.com/ereslibre/flora.git
  git remote add dangergrrl git://github.com/dangergrrl/flora.git
  git remote add crazyfraggle git://github.com/crazyfraggle/flora.git
  git remote add nakaran git://github.com/nakaran/flora.git
  git remote add PaddyMac git://github.com/PaddyMac/flora.git
  git remote add deferi git://github.com/deferi/flora.git
  git remote add ozon git://github.com/ozon/flora.git
  git remote add mma git://github.com/mma/flora.git
  git remote add alexjp git://github.com/alexjp/flora.git
  git remote add funkycode git://github.com/funkycode/flora.git
  git remote add limansky git://github.com/limansky/flora.git
  git remote add fearedbliss git://github.com/fearedbliss/flora.git
  git remote add lebel git://github.com/lebel/flora.git
  git remote add SaThero git://github.com/SaThero/flora.git
  git remote add soulthreads git://github.com/soulthreads/flora.git

• Pull the changed/added files into your copy of flora, where username is the repo of the user that wants to add stuff to flora

  git fetch username

• Merge the branches into flora

  git merge username/master

• Push to ninja2

  git push

• Close the pull request on github, and no worry it will show you problems if you view the code again, as we already included the patch of the user :)

If you as a coreteam member do not have rights to edit issues on flora at github anymore please give User:drobbins or User:golodhrim a ping, so that you can close the request when you merged it... :)

User Contribution

For normal users that like to contribute it is a bit more complicated but we will walk you through it.

First you need to have a GitHub account; you can follow our Git Guide to get one.

Visit https://github.com/funtoo/flora and use the fork button on the top to fork the repository to your own account so that 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. We'll use /root/.git for this example, but you can use whatever you want to.

cd /root/.git
git clone git@github.com:{your github username}/flora.git

Now you are nearly ready to contribute. Since you now have flora cloned to /root/.git/flora, you need to go in and make a few changes so that you can begin your work.

... work with git-flow

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

# emerge -avt gitflow git-flow-completion

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

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

How 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 a hotfix:

# git-flow feature start <name of feature>

You may switch at any time to the development branch again with:

# git checkout develop

To see which features you currently have open:

# git-flow feature [list]

Once your feature is finished:

# git-flow feature finish <name>

For a hotfix to any of your ebuilds:

# git-flow hotfix start <version>

After applying the appropriate fixes:

# git-flow hotfix finish <version>

Now that you know how to add features, hotfixes, and support work, you still need to know how to make a release.

# git add <directory or file>
# git commit
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 can write a release note, save and close your editor afterwards.)

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 you are now on the master branch, you can do the push and go back to the development branch.)
# git push
# git checkout develop

You should now have an overview of how we like to work in flora and keep its contents clean.

This workflow model will then look like the following graph:

... keeping in sync with upstream

To keep in sync with upstream Funtoo flora just do the following steps.

First you need to add a new remote to your configuration, it is really easy and you should sync with upstream from time to time again.

So change to your clone of flora and execute the following commands:

$ cd <path/to/flora/>flora
$ git remote add upstream git://github.com/funtoo/flora.git

That's all, was a one timer. From now we just need to keep in sync from time to time.

That is nearly as easy as the above:

$ git fetch upstream
$ git merge upstream/master

Now you are in sync with our upstream version of flora again. Please do the last two steps regulary (maybe cron?).

Flora Main Ruleset

As we want to keep up the high standard for ebuilds in flora like we provide in our portage trees (portage, funtoo-overlay) you should write your ebuilds clean and with the needed care.

Please respect our following rules:

• Test your ebuilds before pushing them to us.
• generate the needed "Manifest" files for your ebuilds. If they are missing we will reject them and drop your request. The only exception to the previous rule is that your ebuild is a git-based ebuild, as the manifest would then be empty and so not pushed. All other ebuilds need to have one.
• If you write your ebuild please make sure you add the following to your header:

    # Copyright 2012 Funtoo Technologies
    # Distributed under the terms of the GNU General Public License v2
   

• push one ebuild-category at one request! if something is missing we won't need to reject all your requests.
• Add a metadata.xml fill too all your ebuilds, so we know who is responsible for the ebuild. the Syntax is like that:

    <?xml version="1.0" encoding="UTF-8"?>                                                           
    <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
    <pkgmetadata>
        <herd>no-herd</herd>
        <maintainer>
            <email>email1@domain.tld</email>
            <name>Name of Maintainer 1</name>
        </maintainer>
        <maintainer>
            <email>email2@domain.tld</email>
            <name>Name of Maintainer 2</name>
        </maintainer>
        <use>
            <flag name='USE-Variable-1'>Description of Variable 1</flag>
            <flag name='...'>...</flag>
            <flag name='USE-Variable-n'>Description of Variable n</flag>
        </use>
        <upstream>
            <changelog>URL to Online Changelogs</changelog>
        </upstream>
    </pkgmetadata>
   

• Add yourself as a Maintainer for your ebuild to our Page so we users have an option to easily find who is responsible and give him a ping in IRC for errors.

Thanks for following the rules. We appreciate your participation. Please don't forget to add yourself to the Maintainer List, as it would save us some work too.

Notify us about your commit

To make us aware that you committed something go to your GitHub account and send us a Pull Request so we can perform a quick review of your push and include it 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 day's work with flora

At this point you should already have a working copy of flora and you should be knowledgeable about git-flow. You should now be ready to start your daily work with flora.

First you need to make sure your copy of flora is synchronized with the main flora repository.

This should always be done before you start working in flora. To make it easier you can write a short shell script to automate this, 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

When you would like to start a new ebuild for a package you want to add to flora sure you are on the development branch. You can check this with:

The asterisk tells you which branch is currently your active working branch. If it isn't "develop" you switch there with:

Now that you are in the right branch, you may begin your work as your tree should now be up-to-date. :)

Adding a new ebuild

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

Now you can work on the feature. When you are finished with doing all the additions and modifications of the ebuild you are going to push to flora, finish your work with:

Now you can start adding a new ebuild with the same above procedure. To go back to your development branch without closing the feature branch you can do:

This way you will not have included your feature branch with your development branch. You can have several ebuilds developed simultaneously without having to worry about your development branch being compromised. If you want to delete a branch, for instance if the ebuild has already been added by somebody else, do:

Where in the example above, the <branch-name> would be "feature/<name-of-ebuild>". You should now be able to work on the development branch, and commit a new ebuild to your development branch. :)

Doing a hotfix

Let's say that a user of one of your ebuilds has encountered an issue with it, and you already know how to fix the problem. You'll need to use the following command to make a hotfix for your ebuild:

When you are done, you will need to publish your hotfix:

Now your hotfix has been published. Your next step is to push it. Read flora#Submitting your release for more information.

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 learn how to make a release. It's as easy as doing the preparations itself :)

First prepare to push the release.

You should now make the final corrections for your release; if you find out that there are still any problems with your ebuild, fix it now. When you are finished, do:

Now get ready to submit all of your changes :)

Submitting your release

This part is the easiest as you don't have to do anything special.

That was it. :)

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 labeled "Pull Request". Look for the red circle in the following screenshot. :)

After clicking the Pull Request button, you will be presented with a preview page where you can enter a title and optional description, see exactly which commits will be included when your pull request is sent, and also see who will be notified about your pull request:

Markup 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:

We should now be aware of your request and will decide how to handle it. It will usually be approved.

Special stuff in flora

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

We have 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 allow all of us to live peacefully together.

What are the folders there for?

• flora/profiles/docs
  This folder is there for docs if you require a special setup, like using sets for unmasking special stuff.
• flora/profiles/sets
  This folder is there to define a special unmasking set or use flag set for packages you sent to flora. Your sets should be put into subfolders.
• flora/profiles/package.mask
  As you might have already guessed, here you can set masks for packages you have submitted. Please don't mask packages that you haven't submitted yourself, as this can result in a great deal of trouble for the devs, and is something we would prefer to avoid.

rules for flora/profiles/docs

In 'flora/profiles/docs' you will insert docs for special instructions like unmasking your ebuilds if you masked them. While it is preferred to try avoiding the masking of ebuilds, sometimes it is not possible to avoid it. Your doc should be named README.<package> so that users can easily find it.

rules for flora/profiles/sets

In 'flora/profiles/sets' you will insert sets to unmask several ebuilds at a time, for example if you commit 5 packages that are needed to build for testing purposes, and 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 end up with a structure like:

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

The content of such an unmask file might look like the following.

   
#############################################################
# 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 contents of the file to /etc/portage/package.unmask depending on their setup. :)

Rules for flora/profiles/package.mask

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

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

These are just four simple rules that you must follow so that we don't get into trouble.

For 'flora/profiles/package.mask' we recommend the following setup:

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

That way we don't have to worry about 3 people editing the same file and giving us headaches when we merge. :)

If you follow these few rules we are positive that we will get on in a good manner here and live next to each other in peace.

Special note for Flora contributors

All contributors to Flora, please edit your userpage.

• Create an account on our page here if you do not have already, else login and
• go to your Userpage and edit/create it with the Form (Create with Form/Edit with Form Button at the top right) :)
• add all your ebuilds you added to Flora with that form in the format "sys-foo/bar"
• save your userpage.

This will help us to see who was responsible for which ebuild and who we should contact if there is a build failure or problems with the ebuild. Thanks for your help. :)

Other Wiki Info for Flora

All the above info can also be found on githubs wiki page for flora too, just have a view here