Aikau Update August 2015

Introduction

It’s been a few months since my last update on Aikau so I thought it would be useful to provide some information on what we’ve been up to recently. I had hoped that we’d be able to make more regular communications on what is included in each weekly release and although the release notes, the JIRA backlog and sprint progress are publicly available, they don’t provide an enormous amount of context on what we’ve been working on. Internally we hold a Sprint review before each release to share with the teams that depend on Aikau the features implemented and bugs fixed, but this isn’t shared outside of the company.

In an ideal world we’d share a more detailed blog post each week, detailing what we’ve done and provide some real-world use cases of how the updates can be used. This week we released 1.0.33 – our 33rd release of the year (not including hot-fixes) – and our team velocity and processes have comfortably stabilized.

Some sprints we find ourselves working on nothing but bugs (as we prioritize these above everything else); some sprints it’s mostly feature development or infrastructure work (such as getting our unit tests working against a Selenium Grid).

In the future I’ll endeavour to provide more frequent updates, and although I can’t cover in detail everything we’ve been working on over the last dozen sprints, I’d like to highlight a few things that might warrant your further investigation.

So in no particular order, here are a few things that you might like to be aware of…

Button Styling

There is lots of work going on behind the scenes in reviewing Share from a design and usability point of view, some of which will be surfaced in the next release of Alfresco. Aikau faces the interesting challenge of supporting releases both past and future, and one of the new design requirements has been a button design. We needed to find a way of preserving the old button style when Aikau is used on a 5.0.n release but also enabling the new improved style in 5.1.n releases. We’ve achieved this through the use of LESS variables and in particular a single variable that allows us to toggle between the old and new styles.

By default Aikau uses the “legacy” style and Share in Alfresco 5.1 will enable the new style by overriding the variable in the LESS XML file (yes, we know… LESS in XML isn’t great – we still haven’t had the opportunity to do anything about that yet!). This also means that buttons can be easily styled per theme, using those LESS variables.

We continue to push more and more of the widget styling into LESS variables to avoid the need for custom CSS selectors as they will invariably be brittle as Aikau development progresses. If there is a specific widget that you would like to see us update to take advantage of LESS then you should raise an issue.

Multiple Document Libraries on a Single Page

One of the internal component teams that is consuming Aikau is implementing a single page that has multiple Aikau Document Libraries within an alfresco/layout/AlfTabContainer. This has been quite a challenge since we’re not completely finished on the Aikau Document Library, and this exercise has flushed out lots of bugs and allowed us to make some great improvements to our publication/subscription framework to ensure that the Document Libraries don’t interfere with each other (e.g. creating content in the wrong location, refreshing all the lists at once, etc). It’s also focused our attention on fixing lots of the little niggly bugs in our Document Library implementation to make it a more polished experience.

Search Without URL hashing or Infinite Scroll

We wrote the new filtered search page for Share 5.0 long before Aikau was abstracted to a project in its own right and it was written very much with a single use case in mind. Since then we’ve done lots of re-factoring and re-work on our list implementations, and quite rightly we’ve had requests to support alternative ways of providing search – namely with basic pagination and without requiring URL hashing. I’m pleased to say that with the release of 1.0.30 both of these things are possible. This will make it much easier to embed the search widgets within pages that aren’t fully dedicated to search.

Document Library Actions

We know that although Aikau predominantly supports Share it should also support other standalone clients. Since those clients won’t have access to the Share Document Library XML action configuration we needed to find a way in which to support actions in a variety of situations. We’ve settled on a fall-back model in which there are 3 ways in which you can define actions:

  1. Where available the XML configuration will be used
  2. It is also possible to configure in completely custom menu items as actions
  3. When nothing else is available fall-back to metadata evaluated actions.

This last approach requires that we map each of the existing Share Document Library action evaluators into individual AMD modules. This means it becomes really easy to add and remove actions as necessary, as well as insert new actions. Where you want to provide an entirely new action, you simply need to include a service to handle the topic that the action publishes. Hopefully this should make action configuration much simpler to re-use and customize dynamically, based on evaluated extension modules. We’re still a long way from completing this exercise but we have at least settled on an appropriate path.

Form Updates

There is steady incremental improvement on forms in Aikau. There’s still a full UX/design review on the horizon but we have made a few tweaks to the design (in particular how form controls are displayed in dialogs). We’ve also provided the ability to auto-save forms and prevent displaying validation errors immediately. It’s also possible to drive form values to and from the browser URL hash.

We’ve added an additional layout widget for forms that allows form controls to be placed in tabs: it’s worth understanding that you can’t use just any layout widget with a form because they won’t necessarily provide the capabilities to delegate the form-to-form-control communications that enable the dynamic validation, display, enablement, and requirement behaviour that Aikau forms provide.

Finally we’ve added support for dynamically showing and hiding warnings based on the changing values of the fields in the form.

Screenshot showing warnings in a form

Screenshot showing a form displaying dynamically evaluated warnings

Filtered Lists

We’ve extended the alfresco/lists/AlfSortablePaginatedList to create an alfresco/lists/AlfFilteredList. This provides the additional ability to update the request for data to include additional filters. Although this doesn’t perform any filtering on the client, it does enable filters to be passed to an API. It also supports the ability to set the filters as browser URL hash parameters to support back button navigation and sharing of bookmarks. This widget can best be seen in the Aikau Unit Test application home page.

Screenshot of Unit Test Application Index Page

Screenshot showing the Aikau Unit Test Application index page

Debug Log

When the Aikau project first started we had the alfresco/logging/SubscriptionLog widget for debugging communication over the publication/subscription layer. We’ve since replaced this with the much improved alfresco/logging/DebugLog which provides the additional capabilities to clear logs, filter on type or text and has expandable/collapsible payload rendering. We’re going to continue to improve this widget over time (any suggestions that you think would be useful are always appreciated) and you can make use of this already in Alfresco Share when client-debug mode is enabled via the Debug Menu in the header bar.

Screenshot of the DebugLog widget

Screenshot showing the DebugLog widget in a dialog

Dashlets

One of the core benefits of Aikau is its unit testing framework. This allows us to release frequently and be confident that we haven’t caused any regressions from the previous release. When the occasional regression does slip through the net we will hotfix the release containing the bug and add a new unit test to prevent any future regressions. When we first abstracted Aikau from Share we weren’t able to remove all of the core Share/YUI2 dependencies from all modules. Dashlets were an example of this, meaning they couldn’t be used outside of Share and couldn’t be unit tested. We’ve since completely removed all of those Share and YUI dependencies which has enabled us to fully unit test the Dashlet widget. Aikau Dashlets also make full use of LESS variables which means that they can be easily themed in Share.

Layout Widgets

We continue to add layout widgets and improve the behaviour of the existing layout widgets. I thought it would be worth calling out a few of the recent additions and updates…

HorizontalWidgets

The alfresco/layout/HorizontalWidgets widget has been updated so that it now takes into account changes to the visibility of its immediate child widgets. This means that the full horizontal space is always consumed as widgets are displayed and hidden. It does this by using the visibilityConfig and invisibilityConfig attributes on its child widgets, and then resizes and recalculates as they are hidden or revealed. Coupled with the existing ability to mix and match fixed widths, percentage widths, and automatically assigned widths on its child widgets, makes this a very powerful tool for fluid layouts.

FixedHeaderFooter

As its name suggests, the alfresco/layout/FixedHeaderFooter provides the ability to define fixed-height header and footer widget models, with a scrollable central panel. It can be configured to have a fixed height or can automatically grow to consume all of the available vertical space from its offset within a page. This makes it possible to have key controls always visible on the page such as the pagination controls for a list or a menu bar that relates to the scrolling content.

InfiniteScrollArea

The alfresco/layout/InfiniteScrollArea is designed to work with the alfresco/lists/AlfSortablePaginatedList (or one of its descendant modules). It can be thought of as the inverse of infinite scrolling – instead of scrolling triggering the loading of the next page of data, pages of data are continually requested until the available vertical space is used up. If more space is then provided (for example if it was included in a resizeable Dashlet that was then expanded) then more data will automatically be requested.

StripedContent

During a prototyping exercise we looked at various layout options and one that has since been integrated into Aikau is the alfresco/layout/StripedContent. This widget allows for a fixed width vertical column to be added to a page where stripes are rendered across the full width of the page. A few stripe styles are included out-of-the-box that can be configured through LESS variables.

Drag And Drop

The Content Modelling feature in Alfresco 5.1 makes heavy use of the Aikau drag-and-drop capabilities. This has meant that we’ve had the opportunity to flush out lots of bugs and make drag-and-drop in Aikau really simple. All the drag-and-drop modules were re-written (and can be found in the alfresco/dnd package) to be completely abstract to support custom data modelling. Really, this needs a blog post or a set of tutorials in its own right, but the unit test pages should give you an idea of what’s possible. Again, just something to be aware of – at some point it would be great if we could make use of the capabilities for a complete drag-and-drop development environment (we even have a unit test page that allows you to build drag-and-drop data models for this purpose!) – but sadly we just don’t have the bandwidth to work on it at the moment.

Where To Find Out More

It’s a great idea to keep a clone of the Aikau GitHub repository up-to-date so that you can use the Unit Test Application to see examples of all the widgets in action. Although this application is intended for unit testing rather than demonstration purposes it is a great way of seeing various configurations of all the widgets in action.

 

Inside the Jira Version Report

by Christine Thompson

Several months ago we started looking at the Jira Version Report as a means to produce release burn-ups so that we could begin to forecast our deliveries using live Jira data. During the implementation of this chart, questions were raised about what data lies behind it and what events affect the way in which the chart is drawn. Many investigations later, and with great support from Atlassian, I can summarise everything that I have learnt about the Jira Version Report.

How the team velocity is calculated

The velocity of the team is fundamental to the forecast that the chart makes. This calculation counts the number of working days and the total of estimated story points to produce the average velocity per day. It considers the number of days based on the start date of the version, not of any Sprints.

velocity

Explaining the prediction strategy

The process would be as follows:

    • Count the number of days since this version has started and the current date (note: start of the version, not of any sprints)
    • Sum up all points completed until today
    • Divide the latter by the former and you will have an estimated velocity (points completed per day).
    • Simply keep adding up this number until you reach the total estimated points in the backlog.

If all weeks will have the same number of working days, it will be a linear prediction.

Setting the start date of the fix version

If the Fix Version in Jira has no start date set then the graph will begin from the date on which the fix version was first associated with an issue. If this is some time prior to beginning work on the version then the start date of the version should be set to the start date of the first sprint in which issues associated with that fix version were progressed.

Here’s an example from one of my teams. We had a Fix Version which was created quite early on by the Product Owner as he planned a new set of features for the team to work on. It was some time before the team actually began progressing any of these stories in a sprint and the Version Report looked like this, with a predicted completion date of 27th Oct:

StartDatePredictiona

This chart was using the default start date of the date on which the fix version was first associated with a story. When I changed this to set the start date of the fix version to the date of the first sprint in which we progressed the stories for this version, the chart looked like this:

StartDatePredictionb

Our prediction date had been changed considerably, to 24th Aug. This is because the first chart had been including the velocity from February to April, even though the team were not progressing any of the stories. As a result, the prediction was much further out because Jira was including several weeks of zero velocity against the version. When the start date was correctly set at the start of the first sprint which included this version, then the prediction was adjusted correctly.

What makes the chart bend

Generally, the prediction line of the chart tends to be straight. However, under some circumstances, the line will bend on “Today”. This can happen in either direction, inflecting upwards or downwards depending on the event which has caused it. The following are the events which I have found can cause the bend.

1. Non-working days

If there are more non-working days set on one side of “Today” than on the other, then the graph will bend accordingly as it would take a different number of days in the second half to achieve the same number of completed points from the first half.

For example, the graph will bend up slightly when there are more “non-working days” in the first half, prior to “Today”, than in the second half.

2.  Closing and re-opening an issue

There is an open bug with Atlassian (GHS-11735) where, instead of subtracting the story points of a reopened issue, it keeps adding them up. Which then results in the incorrect prediction, where the velocity assumes that the team will speed up in the upcoming weeks and reach the goal more quickly. This means that closing and re-opening issues causes the line to bend upwards.

3. Removing the fix version from a closed issue

Removing the fix version from an issue which is already closed causes the line to bend upwards. (This does not happen with issues that are open, only with those which are already closed when the change is made.)

It’s worth being very cautious about these events, as the bend in the chart is often not reversible. Here’s an example from one of my teams, which resulted from removing the fix version from a number of closed stories:

VersionReportBend

How are scope changes handled?

Changes to scope other than those described above seem to be handled in a consistent and expected way. This includes the following:

  • Increasing / reducing the story points on an issue
  • Adding an issue to the fix version or removing the fix version from an open issue

When such a change is made, this alters the target scope on the right-hand side of the graph so that the prediction line intersects at an earlier or later point, thus giving an updated forecast date. See the following example, where the scope was reduced, giving an earlier forecast for completion:

scope

Estimating the full scope of the project

The Version Report will forecast for the issues that have been estimated and, whist some of the work remains un-sized, the graph will not reach 100% (see above screenshot for an example). There is an open bug with Atlassian for this issue (GHS-12137), as the graph keeps increasing the range of story points when more story points are committed. In this way, the percentage of progress on the project can never reach 100%, as it will always set a higher range of story points, more than the team has committed in the stories.

In conclusion

I have found the Version Report to be a very useful tool in the prediction of the work that my teams are progressing. However, for the report to be widely adopted in our organisation, I think it’s essential that we can understand how it is constructed so that we can trust its output. With very little documentation available online about this chart, I hope that the details that I have collated here can shed a little more light. Happy forecasting!

Is Alfresco’s Product Portfolio Speaking Your Language?

by Andy Healey

Interested in providing feedback and insight to simplify Alfresco’s products?

Over the last few releases of Alfresco One and Alfresco Community Edition, you may have noticed that the user interfaces (UI) have been updated with a slicker, more modern feel. The Alfresco User Experience and Engineering Teams have put a lot of time and thought into creating products that look great and are simple to use. And we’re not finished yet…

What you may not have noticed is that we’ve also been gradually updating the function terminology (everything from button labels to error messages) in the product, to make the language feel more natural, and less clunky or technical. When you use Alfresco’s products we want the terminology to feel like a natural conversation rather than a barrier; terminology that will help guide you, rather than language you have to Google to find out what it means to move forward.

A great example is the new Search Manager feature in Alfresco One 5.0. This feature started life as Faceted Search Configuration – we hope you’ll agree that the name we settled on is a bit friendlier and more commonly used!

Now we want to get you, our end users, involved… We’ve published a survey asking for feedback on what works, what doesn’t, and what direction you’d like to see us go in with the terminology in Alfresco’s products.

We need direct feedback from all members of the Alfresco family – community and enterprise users, developers, architects, partners, consultants, anyone that uses Alfresco’s products! Please let us know what you think – the survey should take no more than 5 minutes to complete and will run until the end of July. Thank you in advance as your feedback will have a direct impact on helping Alfresco product’s speak your language.

Following the survey, we’ll collect and analyze the results to discuss the feedback we’ve received. Once a plan is in place, we’ll report back our findings through a follow-up blog post, so stay tuned.

Click here to give your opinion.

Share Header Colour Customization

by Dave Draper

Introduction

Alfresco Share has supported themes in general for some time, but it is more challenging to customize the colours used in the Share header bar. We’ve made some updates in the Aikau 1.0.18 release that now make this a much simpler process. You’ll be able to take advantage of these in either Alfresco Community 5.0.d or Alfresco Enterprise 5.0.1 if you upgrade the default version of Aikau used, but will be available for use out-of-the-box in Alfresco Enterprise 5.0.2 and future Community releases. This blog post will explain how to create or update a Surf theme to customize the header colours, as well as providing some context on why it has taken so long to provide this capability and the ways in which it will further improve in the future.

A Bit of History…

The current widgets used for the Share header were created during the 4.2 release. At that time we were experimenting with ways in which we could improve theme handling but it wasn’t until after the 4.2 release that we included dynamic LESS pre-processing into Surf page rendering.

Although there was an effort to generate some momentum in updating the Share themes it wasn’t really a priority at the time and as a result the capabilities that were introduced weren’t made use of in the 5.0 release.

It’s only now that 5.0 is starting to get some focus in the field that we’ve started to see questions related to this particular type of customization. It has always been possible to change the header colours by modifying the CSS files directly or replacing them completely, but with the release of Aikau 1.0.18 we’ve gone back through the “alfresco/header” packaged widgets and updated the CSS files to make use of some new LESS variables.

LESS and Themes

Overriding the default LESS variables (which are defined in defaults.less in Aikau and included for every theme) is currently done by adding a particular element to the Surf Theme XML file. I appreciate that it’s not ideal to be writing LESS in an XML file but there are historical reasons for this and in the future I hope to be able to change this so that the Theme XML file can reference one or more LESS files as required.

A Surf Theme is defined by an XML file that lives in the “themes” subfolder of the client’s Surf configuration folder, in Share this can be found in “share/WEB-INF/classes/alfresco/site-data/themes”. If you want to create a new theme for Share that supports the legacy YUI2 widgets you should also create a theme folder with a name that matches your Surf Theme name – if working with a standalone Aikau client (e.g. one created by the Aikau Maven Archetype) then this isn’t necessary.

In the theme XML file include the following within the <theme> element:

<css-tokens>
  <less-variables>
  </less-variables>
</css-tokens>

Within the <less-variables> element you can place any valid LESS content (http://lesscss.org/features/). If we want to override the LESS variables for the header we can add the following content that results in an awesomely garish header:

@header-background-color: #0082c8;
@header-font-color: #ccc;
@header-hover-background-color: orange;
@header-hover-font-color: green;
@header-focus-background-color: yellow;
@header-focus-font-color: red;
@header-menubar-font-color: pink;
@header-dropdown-menu-font-color: purple;
The resulting customized header

The resulting customized header

Variable Breakdown

We’ve tried to make the LESS variables as semantically meaningful as possible, but in case it’s not obvious I’ll break down what each variable does.

  • @header-background-color – This is the main background color for the header (e.g. in Share this is black)
  • @header-font-color – This is the colour of fonts when menus are neither hovered or focused, in Share this is a light grey colour by default.
  • @header-hover-background-color – This is used for the background colour of the header menu widgets when the mouse hovers over them. In Share this is a light grey colour.
  • @header-hover-font-color – This is used as the colour of the header menu widgets when the mouse is hovered over them
  • @header-focus-background-color – This is the background colour of the header menu widgets when they have focus, therefore it is also used as the background colour of drop-down menus (as they have focus when opened). In Share this is a darker grey colour by default.
  • @header-focus-font-color – This is used as the font colour of focused header menu widgets. So it is used as the font colour of items in opened drop-down menus. In Share this is white by default
  • @header-menubar-font-color – This is used as the font colour of menu bar items (e.g. not drop-down menu items). In Share this is the darker grey by default.
  • @header-dropdown-menu-font-color – This is used as the font colour of drop-down menu items. In Share this is white by default.
Editing the Green Theme in Share

Editing the Green Theme in Share

If you look through the defaults.less file in Aikau you’ll see that there are lots of other LESS variables that you can override. Although not all of the widget CSS files make use of these LESS variables we are going to endeavour to improve this over future releases. However, if there are any widgets in particular that you wish were easier to customize then please let us know – it’s very difficult for us to support use cases that we don’t know about, so please let us know by raising issues on GitHub or JIRA.

Aikau Update, May 2015

by Dave Draper

Introduction

I’ve been pretty quiet with blogs and social media of late so I thought I’d provide a bit of an insight into what’s been going on with the Aikau UI framework.

Processes

On the whole things have been going exceptionally well. We’ve managed to maintain our weekly release cycle since the beginning of the year and have now made 18 releases (including 3 hotfix releases which were useful in proving that that element of our development process works).

Although the team is incredibly small (just the two of us at the moment), we’re now servicing 4 different Alfresco Engineering teams working on a variety of projects, along with a small handful of customer engagements.

Because we have such short Sprints we’re able to turn around requirements and bug fixes incredibly quickly, and thanks to our automated unit tests (which just passed the 75% code coverage mark with the 1.0.16 release) we’re able to ensure backwards compatibility.

The test page for a new MultipleSelectInput form control created for another Engineering team

The test page for a new MultipleSelectInput form control created for another Engineering team

Automated Testing

At the moment we only have automated testing against Firefox and Chrome (on a local Vagrant VM) but have already successfully tested against a Selenium Grid that uses Internet Explorer and are looking to start incorporating this into testing in the future. At the moment we still rely on manual testing to pick up IE bugs.

The teams that we’re supporting raise bugs and feature requests as they find them and we prioritize them as necessary, ensuring that bugs are prioritized above anything else to try to maintain zero technical debt.

Recent Code Coverage Results

Recent Code Coverage Results

Educational Material

As well as improving our unit test coverage we’re also trying to improve our JSDoc documentation and when we work on any module we look to try and provide a useful description and examples of how it should be used. We’re still a long way from where we want to be, but we are making steady progress.

Another way in which we’re trying to provide educational material for Aikau is with the new index page for the test application. If you were to clone the GitHub repository and run:

mvn clean install jetty:run

…then you could access the page at “http://localhost:8089/aikau/page/tp/ws/Index” and use the “Filter results” box to search for widgets or services that you might be interested in. We’re updating the unit test WebScript descriptor files to set more meaningful “shortname” and “description” values – once again, this is an ongoing process.

Unit Test Index Page

The Unit Test Application Index Page

Document Library

Although our primary goal is to support the other Engineering teams development work we have an ongoing background task in porting the Document Library over to use Aikau. When we initially started looking at this back in the very early days we were only trying to port the existing capabilities and find ways to harness the existing action handling code. Now we’re looking to improve the Document Library with features such as inline commenting; inline content creation and metadata editing; popup previews; and drag-and-drop version update. We also want to make sure that it’s possible to easily create a configurable Document Library within a Share page and a standalone Aikau client via library files that can be imported into your Aikau page WebScripts.

The Document Library isn’t in bad shape at the moment – the biggest challenge now is to work through the remaining actions that aren’t supported and find the best way of being able to support legacy Share based XML configuration for actions, as well as making it easy to use actions in non-Share based standalone clients. You can follow the progress we make by cloning this GitHub repository which is a simple Aikau client with a page showing the authenticated user’s “User Home” directory. It would be really good to get some feedback on what we’re doing – particularly with regards to whether or not you’d be able to customize this Document Library more easily to fit your specific use cases.

DocumentLibrary

The work-in-progress Aikau Document Library

Pull Requests, Feature Requests and Bug Reports

The only less positive to report so far is the lack of pull requests that we’ve received. The Alfresco Community were apparently clamouring for an easier way of contributing code to Alfresco and Aikau provides the easiest way to do that so far. It’s possible that this is because it’s still very new and that only the recent 5.0.1 and 5.0.d releases support the external Aikau libraries.

I do see that we get a lot of traffic on the GitHub site (around 50 unique visitors per day) and that the tutorials are getting a lot of hits. We’ve also had a couple of external issues raised which we’ve tried to turn around as quickly as possible.

A screenshot from one of the tutorials hosted on GitHub

A screenshot from one of the tutorials hosted on GitHub

I also note that there is still some general concerns about Aikau in the Alfresco IRC channel. Maybe this is to be expected as Aikau still needs to prove it’s worth in the field – but I can say that the feedback within the company is incredibly positive and Aikau is definitely showing its value in accelerating the rate of UI development work internally. Hopefully once we’ve set out the ways in which Aikau can guarantee future-proof customizations from release-to-release of Share then the benefit will be seen outside of Alfresco as well. One thing I would say is that the discussions on IRC never materialise into issues on GitHub or JIRA – if you have something you want fixing or improving then let us know! We’ve already implemented feature requests and bug fixes that came from the forums and have added others to the backlog to work on in future sprints.

Long Term Thinking

We know that we’re not following the latest trends (interestingly I’ve noticed that the conversation about the best UI framework to use has shifted from Angular to React in recent months, no doubt it will have moved on to something else 12 months from now) but there’s no reason to think that Aikau won’t be around for the long haul – especially when you consider that the vast majority of Share is built on YUI2 which is approaching its 10th anniversary. Our black-box, widget-based, declarative approach to page creation is also holding strong with rewrites and updates to widgets being made without needing to make any changes to the pages that use them. We’ve also been able to migrate from Dojo 1.9.0 to 1.10.4 fairly seamlessly where our unit tests were able to quickly identify the few bugs that the upgrade introduced.

Summary

So in summary it feels as though we’re on the right track. Our processes are working, we’re making regular releases, code coverage is steadily increasing, JSDoc is improving and we’re adding more widgets and services every week. If you’ve not tried out Aikau then why not follow the tutorial and see how easy it is to quickly develop reliable, web-based clients for Alfresco.

Sample JSDoc Page

Sample JSDoc Page

Understanding the Jira Burn-down Chart

by Christine Thompson

The Jira burn-down chart tracks the total work remaining in the sprint and projects the likelihood of achieving the sprint goal. By tracking the remaining work throughout the iteration, a team can manage its progress and respond accordingly. Having spent some time getting to grips with the intricacies of the burn-down chart, I thought that I would share my understanding. 

The green line is the burn-up line which indicates the time spent ie. the sum of all the hours logged against the tasks in the sprint. The red line is the burn-down which indicates the time remaining ie. the total estimated time in the sprint minus all the hours that have been logged. You may well expect that as the sprint progresses, the time burnt-down on the red line will equal the time burnt up on the green line but it seems that this is often not the case. 

Here’s a snippet from a recent burn-down chart for one of my teams, mid-sprint:

 burndown1

You can see that the time indicated on the axis for the burn-down is 84 hours but the time indicated on the axis for the burn-up is 60 hours. So we have logged less time than we estimated we would need. For example:

 timetrack1

If this consistently happens, it tells us something about us overestimating the time we need on our tasks. However, perhaps of more concern would be the converse of this. For example:

 burndown2

Here, we have burnt-up more work than we burnt-down. This is because you can log more hours than you have estimated, for example:

 timetrack2

However, you cannot have a negative time remaining. If you log more than you estimated, the remaining stays at zero. This means that the total represented by the time spent (green) line can exceed the total represented by the time remaining (red) line and indicates that work is taking longer than we estimated. 

What happens if we increase our estimate because we find out, part way through, that a task will take longer than originally thought? This is where we see the upward spikes in the time remaining (red) line, as indicated above. The start point of the ideal work (grey) line and the start point of the burn-down line do not adjust on the axis to reflect that the additional work has been added, so this exacerbates the difference between the apparent burn-down progress and the amount of work completed on the burn-up.  

If your estimates were exactly correct, then adding the time for the scope increases to the apparent burn-down value should then equal the amount of work logged in the burn-up. This isn’t the case in the example above (ie. 35h + 20h + 4h still does not equal 70h) because we are also suffering from under-estimating the time that the tasks will take. 

Given this understanding of what the lines on the graph reflect, it appears that there is useful information to be had here about the accuracy of estimating, especially where we are taking longer on tasks than expected, which may need some further investigation. However, I would only be concerned if this were a regular trend and was matched by a similar discrepancy in the story points estimated and completed within the sprint.  

One final thought is that we do, of course, want the burn-down to reflect reality and not just match the ideal progress line. So being honest about the progress of the work in a sprint is far more important and useful to the team than artificially logging work to achieve a perfect burn down.

A helping start when moving from Silo’d working

by Tristan Bagnall

I often find when teams move from working as a collection of individuals with a shared purpose, but in different silos that they needs a helping start on when to communicate with each other.

Naturally there are points in time where Scrum creates the opportunities, but those opportunities are not enough for a performing team.

I don’t intend on going into how to communicate in the Scrum ceremonies, but rather share some thoughts on how to start teams effectively talking.

Here are the guideline I give teams:

When you are about to pick up a new user story have a quick chat with the team – all the cross functionals (Coding, testing, documenting, deploying, user experience, etc.) to:

  • … ask if there is anything you can do on a currently in progress user story to help get that completed first.
  • … make sure the story is still good – incorporating anything we may have learnt so far in the sprint. Include the PO in this.
  • … make sure the plan on how to complete the user story is still right – it might need updating based on what we have learnt so far in the sprint.
  • … make sure the tasks represent he plan to complete the user story and have enough information to enable anyone to pick them up.
  • … ensure there are the right people available to work on the user story. If you have specialisms in the team make sure there is someone from the cross functionals to work on the user story, such as a tester to ensure a coder knows what to produce to pass tests.

This conversation would normally be anywhere from 30 seconds to 5 minutes, unless we have learnt something that causes he plan to change considerably.

When you are about to pick up a new task:

  • … ask other team members if they need any help on what they are working on, to help them get their task completed.
  • … check that your approach is going to be correct for the task at hand with another team member. For example
    • a coder may check with a tester before implementing code to ensure they understand the tests, edge cases, negative paths, etc. that they need to cover.
    • a tester may check with coder or user experience to see how they are thinking they would add a button to a user interface to ensure their automated tests would capture it

This is a start for teams, and once they get into the flow they will adjust and improve, probably without even thinking about it.

So, when is Alfresco moving to GitHub?

“When are you moving to Git/GitHub/Bitbucket/decentralised version control software/…” must be the most frequent question I get, both from people inside and outside of Alfresco.

I usually start by explaining that Alfresco is on GitHub! The Alfresco organisation there currently owns 35 public repositories, and many of them are very active. All our mobile code has been there forever; for instance: (iOS + Android) * (SDK + App), as well as Aikau, Gytheio, the Alfresco SDK, etc. The recent announcement that Google Code is going to shut down triggered another batch of migrations to GitHub, such as Jive Toolkit, dropbox integration, and more.

Of course, what the question really means is: “When is the Alfresco Platform codebase moving? Not some petty integration or client app.” :-) Well, we do have a mirror of the Community Edition source on GitHub. But as for moving the whole code base there, the answer is: never — at least in its current form. Here are a few reasons why.

  • It doesn’t fit!
    GitHub has a limit of 1GB per repository. We hit that limit for the mirror, and had to filter a few big folders. (Even Linux had to cut down the history of the repository to move there!) Of course, we used to commit big jar files in the source. We don’t any more, but even then, we still cross the limit. And it’s not just GitHub but all DVCS: holding all the history of the repository in your local copy has a big impact if you have a 10 year old code base of one million lines of code!
  • Continuity with past releases
    We could make a clean cut, leaving the Old World in Subversion and having the Brave New World in Git. That would work, but it would make merging modifications from earlier maintenance branches very hard — and most of our commits are of that kind! We have 4 active service pack branches (4.1.x, 4.2.x, 5.0.x) and 18 active hotfix branches (from 3.4.14.x to 5.0.1.x) All fixes have to be merged forward, so that people don’t get regressions when upgrading. Doing this is tedious enough without having to switch software in the middle!
  • Access rights
    Our Subversion repository is currently a patchwork of access rights, and DVCS don’t support that — the idea being that you spread your software in smaller repositories, and manage the rights for each repository. Even in a given branch, we have folders which are public (Community Edition), others which are reserved to customers (Enterprise Edition) and others which are private (Cloud Edition).
  • Big team, big problems
    I don’t want to manage a Git repository where 50 people (and counting!) commit daily. DVCS are inherently more complicated than centralised systems (think of what identifies a revision, for instance), which certainly allows for more power, but also more headaches in big teams where not everyone has a PhD in Gitology!

However, don’t despair. We are not stuck in this situation forever! As you saw earlier this week, we are currently working hard to make the code more modular, and to extract from our big codebase some independent, consistent pieces that can be released separately. You’ve seen this already with Aikau and Share (but it also happened a while ago with Records Management, and all the integrations).

As we extract smaller chunks, it can make sense to move them over to GitHub, because they will then be more manageable and will have a small team of people responsible for it. The goal here is twofold: externally, to release more frequently to our audience, and internally, to allow more parallel developments to happen and be more agile.

I hope you are as excited as we are about this change – this is much more interesting than just changing our SCM software!

Adding Views to Filtered Search

by Dave Draper

Introduction

One of the Alfresco Solutions Engineers recently contacted me to ask how easy it would be to add a table view into the new filtered search page in Alfresco 5.0. Fortunately this page is built using the Aikau framework, so this is actually an incredibly easy task to accomplish. This blog will take you through the process. If you have trouble following the steps or just want to try it out then download the example extension module from here.

Extension Module Creation

The best practice to customizing Alfresco Share is to first create an extension module, and for Aikau pages this is a very straightforward process. First of all ensure that Share is running in “client-debug” mode.

Now login to Share and perform a search so that the filtered search page is displayed.

Filtered search page

Open the “Debug” drop-down menu and select “Toggle Developer View

Debug Menu

You should see a page that looks like this:

Developer View

Now click on the link at the very top of the page that says “Click to generate extension JAR”. This will generate a JAR file containing all files required to customize the filtered search page.

Unpack the JAR file and open the “/alfresco/site-webscripts/org/alfresco/share/pages/faceted-search/customization/faceted-search.get.js” file in your editor of choice.

Now go back to the filtered search page (still in developer view) and click on the info icon for the main list. It should display a tooltip indicating that the widget selected has an id of “FCTSRCH_SEARCH_RESULTS_LIST”.

Selecting the Search List

Copy the “Find Widget Code Snippet”, it should be:

widgetUtils.findObject(model.jsonModel.widgets, "id", "FCTSRCH_SEARCH_RESULTS_LIST");

Paste this into the “faceted-search.get.js” file that is open in your editor. This snippet of code is all you need to target a widget on an Aikau page (obviously each snippet of code is different for each widget on the page), and in this case you have targeted the main search results list.

Understanding the extension

Lists in Aikau are used to manage data and delegate the rendering of that data to one or more views . We want to add an additional view into the search page.

There is lots of information in the Aikau tutorial on creating views, so I’m not going to repeat that information here, but if you’re not familiar with defining a list then you should certainly work your way through the tutorial.

To add a new view you just need to “push” a new widget declaration into the “widgets” array of the search lists “config” object. You can create any view you like, but as a relatively simple example you could create the following (this would be the complete contents of the faceted-search.get.js file):

var widget = widgetUtils.findObject(model.jsonModel.widgets, "id", "FCTSRCH_SEARCH_RESULTS_LIST");
if (widget && widget.config && widget.config.widgets)
{
   widget.config.widgets.push({
      name: "alfresco/documentlibrary/views/AlfSearchListView",
      config: {
         viewSelectionConfig: {
            label: "Table View",
            iconClass: "alf-tableview-icon"
         },
         widgetsForHeader: [
            {
               name: "alfresco/documentlibrary/views/layouts/HeaderCell",
               config: {
                  label: "Name"
               }
            },
            {
               name: "alfresco/documentlibrary/views/layouts/HeaderCell",
               config: {
                  label: "Description"
               }
            }
         ],
         widgets: [
            {
               name: "alfresco/search/AlfSearchResult",
               config: {
                  widgets: [
                     {
                        name: "alfresco/documentlibrary/views/layouts/Row",
                        config: {
                           widgets: [
                              {
                                 name: "alfresco/documentlibrary/views/layouts/Cell",
                                 config: {
                                    additionalCssClasses: "mediumpad",
                                    widgets: [
                                       {
                                          name: "alfresco/renderers/SearchResultPropertyLink",
                                          config: {
                                             propertyToRender: "displayName"
                                          }
                                       }
                                    ]
                                 }
                              },
                              {
                                 name: "alfresco/documentlibrary/views/layouts/Cell",
                                 config: {
                                    additionalCssClasses: "mediumpad",
                                    widgets: [
                                       {
                                          name: "alfresco/renderers/Property",
                                          config: {
                                             propertyToRender: "description"
                                          }
                                       }
                                    ]
                                 }
                              }
                           ]
                        }
                     }
                  ]
               }
            }
         ]
      }
   });
}

We’re pushing in a new “alfresco/documentlibrary/views/AlfDocumentListView” that uses the table view icon (“alf-tableview-icon“), has a label of “Table View” (which we could have localized if we wanted) and a value of “table”.

The view has two header cells (for name and description) and each item in the list is rendered as an “alfresco/documentlibrary/views/layouts/Row” widget containing two “alfresco/documentlibrary/views/layouts/Cell” widgets.

The first cell contains “alfresco/renderers/SearchResultPropertyLink” that renders the “displayName” of the item and the second is a simple “alfresco/renderers/Property” that renders the description.

Testing out the view

Re-package the extension files as a JAR file, copy that JAR file into the “share/WEB-INF/lib” folder and then restart the server. When you perform a search you should see your table view as an option.

Selecting the view

Selecting the table view will show the search results as:

Search Table View

You can add more columns to your table view, but it’s important to understand that the API used on the search page only retrieves a very small set of Node data. The data that is available for each node found is:

  • displayName
  • description
  • mimetype
  • modifiedBy (user display name)
  • modifiedByUser (username)
  • modifiedOn
  • name
  • title
  • nodeRef
  • path (within a site)
  • site (if the node is in a site)
  • size (in bytes)
  • tags
  • type (e.g. “document”)

If you want to display more than than this limited set of data then there are a couple of options available.

One approach that you could take is to use the “alfresco/documentlibrary/views/layouts/XhrLayout” widget that allows an initial version of the view to be rendered for an item (using the limited data set) and when that item is clicked the full node data is requested and the “full” view is then rendered using that data. However, this widget is only a prototype and should only be used as an example.

Another option would be to extend the “alfresco/documentlibrary/AlfSearchList” widget to request the full data for each node before the view is rendered. This would naturally slow down the rendering of search results but would allow you to display any of the data available for that node.

Deprecations

The example used in this blog will work on 5.0, but you should be aware that some of the widgets referenced have now been deprecated in later versions of Alfresco. The deprecated widgets won’t be removed for a long time, but if you’re customizing 5.0.1 onwards then you should look to use the latest versions. All deprecations are listed in the release notes for Aikau.

Screen Shot 2015-03-31 at 4.34.51 PM

Release Agility – Update I – Share source location changes

If you are a member of the Alfresco Development ecosystem or you attended one of the recent Alfresco events, you might have heard of the Release Agility project, a major investment we are doing at Alfresco to improve the pace, quality and modularity of our development and release process.

And if you monitored the Alfresco Public SVN and/or you build Alfresco from sources, you might have noticed some substantial changes in our source code layout, specifically related to the Share webapp location.

In case you were guessing, yes, these two items are tightly connected and in fact the changes in SVN changes are just one of the initial steps of the larger process improvements driven by the Release Agility project.

So, in the spirit of open communication and in pure Sinek-ian fashion, let me give you a general idea of the changes, starting with why we are doing this.

Continue reading