{{admon/warning | Use your own branch for pushing! | Features under development are not pushed directly to ''devel'' or ''master'' without being tested and approved by the team.}}</li>

+

</ol>

+

+

==== Merging to ''devel'' ====

+

+

{{admon/note | Only merge completed features | Your feature will go live on the development site. Don't panic if there's a bug; that's why we have a development site. But do wait until you're finished.}}

+

+

<ol>

+

<li>Make sure you are on the ''devel'' branch, and that you have the latest content:

+

<pre>git checkout devel

+

git pull</pre></li>

+

+

<li>Merge the changes:

+

<pre>git merge mqjones-social-networking</pre>

+

Resolve conflicts, if any.</li>

+

+

<li>Tag the new head according to the feature version you set and the "-test" suffix:

+

<pre>git tag social-networking-0.2-test</pre></li>

+

+

<li>Push the results:

+

<pre>git push --tags</pre></li>

+

</ol>

−

<li>Make a new directory

+

==== Merging to ''master'' ====

−

<pre>mkdir my_awesome_feature</pre></li>

−

<li>Copy your feature files

+

{{admon/warning | Only merge tested features | Your feature will go live on the production site. Don't do this until the team approves the change.}}

−

<pre>cp path/to/my/feature/* ./my_awesome_feature/</pre></li>

−

<li>Add the directory of feature

+

<ol>

−

<pre>git add my_awesome_feature/</pre></li>

+

<li>Make sure you are on the ''master'' branch, and that you have the latest content:

+

<pre>git checkout master

+

git pull</pre></li>

−

<li>Commit your changes

+

<li>Merge the changes:

−

<pre>git commit -a -m "My awesome feature has been added"</pre></li>

+

<pre>git merge devel</pre>

+

There shouldn't be any conflicts, but if there are you might want to let someone know before you go any further.</li>

{{admon/note | Use ''devel'' branch for pushing | We use a different branch for the production status. Features under development are not pushed directly to that branch without being tested and approved by the team in some fashion.}}</li>

Contents

What is the Features module?

The Features module allows us to build custom features that don't involve programming by hand. We can organize the each part of our Insight page into one or more feature like a custom module. For instance, we could create a new feature like a "Super Event Calendar."

How does this work?

A Feature itself (with a capital "F") is constructed out of exportables created by existing modules that the Features module understands (either intrinsically or because those modules support the Features API). This sounds a lot more complicated than it is.

For example, imagine that you want to create a capability on the Drupal 6 server that involves a few custom Views, and perhaps some custom CCK fields. You can gather these customizations (let's call them "exportables" here) together and give that collection a name using the Features module. The Features module creates a set of custom code, which it can then export as a module. The code can then be managed through a SCM repository, allowing for change management.

To create a custom super feature, click Create feature at the top on the create feature page. Fill out the requirements (Name, Description, Version) as desired, then select settings in the Edit components section. When finished, select Download feature.

After this process, you can upload your custom feature on the server into the sites/all/modules directory.

To use a custom feature you've created, visit the Features page, select the checkbox for that selected custom feature, and select Save settings.

How Insight uses Features

Git branching and merging

We use two official git branches for Feature management for Insight. The devel branch is used to power our development site, and the master branch is used for the more official staging and production sites.

However, developers are asked not to push directly to either of these branches.

Instead, developers work on their feature on a separate branch of their own. Recommended naming is something like <username>-<feature-description>. An example might be mqjones-social-networking. Push these branches as is, to the repository (making a new remote branch as needed). This way, we can work on multiple features at once, and developers can share or collaborate as needed without leaving any of our live sites in an uncertain state.

When a feature is complete and ready for developer testing, merge that branch to the devel branch. Reference all tickets addressed with this feature in the commit log (the text ticket 423 is fine). Individual references in several commits is fine too. Remember the purpose is to make your work very clear to someone looking at it later when you're not around to explain it.

Once you complete the merge, resolving any problems, tag the resulting commit with the feature name and version, such as social-networking-0.2. The development site will pull any changes within an hour, or one of the admins on the team can manually pull if needed.

Following testing, once the team has approved the change, merge the devel branch into the master branch. The production site will automatically pull the changes from master.

Procedure

Initial work

Clone the repo:

git clone ssh://git.fedorahosted.org/git/fedora-insight-features.git

Change the directory:

cd fedora-insight-features

Make a new branch for your work:

git checkout -b mqjones-social-networking

Changes If you're changing an existing feature module, you can use the existing directory; you don't need to make a new one. This makes merging easier.