Overlay:Flora
Contents |
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.
- A group of plants, especially the indigenous plants of a particular time or region.
- A book or treatise describing the plants of a particular region or time.
- 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 git@github.com:funtoo/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.
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. Let's say you use /root/.git for it, but you may 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. 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 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 git-flow for it. In the following example 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
at any time again. 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 know 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 can 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 committed something go again to your github.com account and send 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 day's work with flora
At this point you should should already have a copy of flora and you should be firm with the git-flow extension... so we are ready to start our daily flora work 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:
| $ git remote add upstream git://github.com/funtoo/flora.git |
then you can keep updated with flora via the following command sequence:
| Description: Keeping flora updated with upstream | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| $ git fetch upstream remote: Counting objects: 54, done.
26 files changed, 1430 insertions(+), 1 deletions(-) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
| $ git branch * develop |
it tells you with the asterisk your currently active working branch and if it isn't "develop" you switch there with:
| $ git branch develop |
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
| Description: Creating a feature branch for the work you do | |
| $ git-flow feature start <name-of-ebuild> | |
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.
Now 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
| $ git-flow feature finish <name-of-ebuild> Switched to branch 'develop' |
so now you can start adding a new ebuild with the same above procedure, you can always do
| $ git checkout develop |
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 :)
That way you can have several ebuilds developed simulatiously without having to worry about your develop-branch beeing compromised, if you want to delete a branch as the ebuild has been added by someone else already do
| $ git branch -d <branch-name> |
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:
| Description: Starting a hotfix | |
| $ git-flow hotfix start <ebuild-name-you-do-the-hotfix-for> Switched to a new branch 'hotfix/<ebuild-name-you-do-the-hotfix-for>' | |
Now you add all the stuff you need to fix the ebuild and then you are ready to publish your hotfix for it.
| $ git-flow hotfix finish <ebuild-name-you-do-the-hotfix-for>
Deleted branch hotfix/<ebuild-name-you-do-the-hotfix-for> (was 2c52d0d). |
Now your Hotfix has been published. Next ist to push it. For doing that, 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's as easy as doing the preparations itself :)
just be ready to make the release
| Description: Preparing the release | |
| $ git-flow release start <desc-of-release> Switched to a new branch 'release/<desc-of-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. When done do
| Description: Finish the release | |
| $ git-flow release finish <desc-of-release> Summary of actions: | |
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
| Description: Submitting to your Fork of flora | |
| $ git add . $git commit | |
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 that you haven't submitted yourself. 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. 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/package.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/package.mask' we advice the following setup:
flora/profiles/package.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.
