The MyFoundation Portal (1 of 12)

Committers on technology projects Dash and Phoenix have just gotten a taste of the Eclipse MyFoundation portal. Both projects have run committer elections through the web-site/email hybrid we are now beta testing.

Phoenix lead, Denis Roy, said, "Using the Portal for the whole Committer Nomination and Election process has been a real charm ... the portal guided me through each step without having to dig through pages of explanation."

The portal will provide a summary of ongoing interactions between our users and the foundation. Our users will conduct foundation business with various components, forms and buttons really, assembled on their portal page. Here is what Mr. ExecVP (a design persona) might see on his portal page:


This simplest of components shows Matthew ExecVP the contact information we have on file for him. Should he want to revise it, he clicks [edit] and gets:



All of our components follow this status/action formula. Also, each one can be customized based on the roles one plays within the foundation. For example, committers will find an extra check off about employment on their address change form. That's because we are required to keep up with our committers' job changes. Have a look at your portal page at this easy to remember address:

portal.eclipse.org

The portal complements business processes now conducted only by email. It will generate status messages directed to both users and foundation email lists. These messages often invite users to visit their portal page in order to interact with the foundation in specific ways.

Portal Voting (2 of 12)

The new committer election process is among the Foundation's most involved work flows and offers a good example of what the MyFoundation portal can do. Let's take a peek at how an election looks on the portal for an existing committer, in this case our hypothetical Ms. Lucy Programmer, one of two members of the equally hypothetical "technology.foo" project.

We pick up the story after Lucy gets automatically notified by email when foo's other committer, Mr Alex Developer, nominates Mr. Karl Candidate to be a committer. Lucy follows the email link to her portal page and finds this component among others provided by the MyFoundation portal:


Before voting herself, Lucy takes a look at the bugzilla, dev-list, and newsgroup posts that Alex mentioned in his nomination. She also takes a look at the votes cast so far by clicking the [votes] link in the top-right corner. The component flips to this view of the voting process:



It says Alex voted +1 to his own nomination and Lucy hasn't voted yet. With less than three committers on the project they all have to vote. Lucy [revert]'s back to the voting view to casts her own +1 .

The portal puts links in square brackets when those links just flip views. New views will show you additional information for a component or give you more choices without actually changing anything. Only the component's buttons take action on your behalf and even then these actions are often reversible.

Lucy's vote flips the view to the running summary with options with which she can review voting progress and even reconsider her own vote.


As time goes by this component shows Mr. Karl Candidate's progress through subsequent stages of approval, paperwork and provisioning. Hmm. This nomination is stalled waiting for paperwork. What else is new?


If Lucy had several elections in progress, maybe on several different projects, her portal page would have separate components for each election and they would each operate independently, keeping things straight for her. Likewise, the PMC and EMO have portal pages with their own views into this and other elections.

Portal Transparency (3 of 12)

The MyFoundation portal will show you what happens when you press a button. Remember, buttons are the only portal widgets that take action. Next to every portal button is a link to the portal Processs Explorer. You can use the explorer for both quick, context sensitive help, and for in depth exploration of our processes.

Here is what the explorer looks like when you get there from the new-committer vote button. The explorer comes up in a new tab or window so that you will have lots of room to look around. (Click on the screen shot below to see what this looks like more clearly.)


The above is just the first page of the explorer. It searches through a catalog of every tested portal use case and selects those that include pressing the vote button. The explorer finds ten, most of which have votes cast in multiple places.

We are making a philosophical leap now so I want to draw your attention to it. The portal process explorer has access to every test case we run, in essence, everything we know about how the portal works, and it is ready to show them to you.

Here is page two of the process explorer. This is what you see when you select a specific use case on page one. What we've done here is run the test on the currently installed portal code, captured screen shots along the way, and rendered them in a single visualization inspired by the "swim lane" diagram made popular by process engineers.



Again, click on the above picture to see more detail or bring up the live process explorer here. There is a lot of information in each one of these diagrams. Important views show up as small boxes. Hovering over a box shows captured details in a bubble. The boxes are organized into columns depending on who sees what. Things happening at the same time are more or less aligned horizontally with the exact sequence of events noted by the small grey numbers. Some emphasis is added to screen shots to highlight changes.

We use the process explorer as part of our test-driven development method. We've made it a part of the portal itself so as to be completely transparent regarding the processes we encode. We expect lively discussions on foundation lists citing explorer URLs and step numbers just as we have always hoped to see lively and productive conversations about all things Eclipse.

Portal Email (4 of 12)

The MyFoundation portal supports you by keeping and consulting its own database records. In addition, the portal keeps all appropriate parties informed of your work by sending necessary emails on your behalf.

For example, we saw a hypothetical committer election in part 2 of this series. When Alex (developer1) nominated Karl Candidate, Lucy (developer2) got email that an election was in progress. Here is what that email looks like in the process explorer. Green highlights mark text we look for in our automated tests:

Notice that this mail when straight from Alex to Lucy. The portal sent it for Alex after looking up technology.foo committers in the foundation database.

Alex should think of the portal as one more email agent working quickly and quietly on his behalf. Several more notices go out from Alex before the whole process is over. For example this one goes out to the foo-dev list when the voting phase completes:


We've noticed a couple of things as we've been beta testing portal voting. For one, it is really hard to keep track of who is doing what when all messages come from portal@eclipse.org. That's why we dropped that alias and now carefully attribute email to real people or groups.

We've also noticed that the foundation records weren't always up to date. We've been cross checking everything and really appreciate the help we gotten from project leads tracking down loose ends.

Today the portal is squeezing itself into our email world. However, we hope that some day soon the portal page will stand above our inboxes as the one place that knows what's going on between us.

Portal Spike (5 of 12)

I've described the MyFoundation portal in parts 1, 2, 3 and 4 of this series. I'll use some of the remaining eight parts to describe how it was written.

We started thinking seriously about the portal when John Tibbits and Barbara Bernstein walked us through their Eclipse based WorkThru Framework using our committer voting process as the test case. Theirs is an awesome system that captures decades of experience with both objects (something we loved) and long transactions (something we had).

We were eager to move forward with WorkThru until we bumpted into the reality that eclipse.org is a PHP shop. Why this is true deserves a whole blog series of its own. It is true so we had to ask ourselves this question:

• what is the simplest PHP script that would give us the objects we like and the long transactions we need?

The answer became the system architecture that we use today:

• a portal.php script as the entry point,
  
• a catalog of components that it can include,
  
• and a class library that collects common code.
  

We wrote this up as a "spike" solution. In the style of "hello world", a spike is just enough of all the parts to understand how they might work in a real solution. Here is what our spike portal looked like:

We cobbled up name, vote and invoice components and instantiated (nonsensically) 2 names, 1 vote and 0 invoices. Here is the portal.php code that did this work:


Each component offered up a factory that would determine which of its instances appeared on the page. The appearing part was done by the next block of portal.php code:



Each component is wrapped in a div tag. The component is responsible for the tag id, the initial html, and javascript that allows further editing. Here is what our spike looked like when I'd clicked the edit link on the second name:

By this time the name component has been cluttered with more javascript than you want to see here. Instead I will close this post with the still hello-worldish vote component that is playing along with name.


Our portal grew from these modest beginnings. In fact the portal is still a modest piece of code. There are only a few places where we've worked hard to extend this paradigm, and we've always done so with practical motivation. I'll describe each of these in subsequent posts.

Portal Entry Points (6 of 12)

In part 5 we saw how the MyFoundation portal components produce html fragments that are assembled into complete portal pages by the entry point, portal.php. Here is a screenshot of Ms. Samantha Strategic choosing a new accounting contact which she can as a strategic member.


Ms. Strategic has chosen to [edit] the contacts for Big Co., her employer. Javascript in the contacts component retrieved this second face through an alternate entry point, dispatch.php. Portal.php gets the first face of all components while dispatch.php gets subsequent faces for a single component.

The portal makes a lot of use of alternate entry points. The swim lane diagrams we saw in part 3 are provided by a third entry point, swim.php. It sets up a test database and runs through a test script capturing html from each component as it goes. Swim.php actually edits the html to show what a component looks like right before the add button is pressed. It also adds some highlighting to make it clear which fields the test script changes.



Here is a fourth entry point, run.php, which we use when developing new components. It runs the same test scripts as swim.php, but does a lot less post processing. Notice that it shows the editor face as it would first appear, before fields are entered. It also shows the full text of each test script line as it is performing them while swim.php just shows the line numbers.


We've seen four entry points, two for normal operation and two more used in testing. All four of these are deployed to production servers. We've commented before how unusual this is, deploying one's test environment in production. Our entry point scripts allow us to exercise the available components and render their products to meet diverse purposes including new applications of functional test.

Portal Index (7 of 12)

The MyFoundation portal provides a place to take action. This complements our dashboards which provide a place to browse status.

The portal is organized as the catalog of components introduced in part 5 of this series. Components offer actions that advance use cases, a second organizing concept. Our use cases can be tested and those tests visualized as described in part 3.

We can see the whole portal all at once in the Use Case Breakdown shown here:

This report cross-tabulates components on the left with actions across the top. The cells count the number of times a specific component-action occurs in our use-case suite. The counts link the process explorer, our mechanism for viewing use cases in swim lanes.

We build this table by logging every action we encounter while running tests. The table shows actions like [edit] and [revert] that aren't themselves buttons and would not have an explore link in the UI. Consider them a bonus.

Here is another bonus. The table shows the various objects that a component's factory will produce. Shown in gray, the variant objects are produced when distinct user roles demand significantly different actions. See, for example, that the pmc and the emo have distinct variations of committer vote.

In summary, the portal supports foundation processes. Processes are exposed as components expressed as objects that vary with role and offer actions. Actions advance use cases, our testable subdivision of foundation process. This all comes together in the portal's use case breakdown.

Portal Workings (8 of 12)

Smalltalk-80 had the exceptional property that you could learn how things worked by just typing ctrl-c. This suspended the work in progress and displayed it's implementation as source. You could learn the native programming language this way and learn lots of technique that would apply in all kinds of environments.

Wiki duplicated this property by adding an Edit button to the bottom of every web page. Wikipedians have shown that this can induce ordinary folk to craft consistently beautiful pages while evolving their own style rules and operating procedures. We don't know to what degree wiki markup contributes to this success, but we can be sure that immediate access to the markup is essential to wiki's success.

The MyFoundation portal, once again, respects the curiosity and intellect of its users by exposing all aspects of the processes it supports. Who asked for this? No one. No one thought to. That doesn't mean it isn't needed.



Brian Marick calls this Visible Workings. He identifies a middle ground, between the traditional GUI presentation and the raw source code that produces it. This middle ground makes the application both explanatory and tinkerable. The portal's swim diagram is our middle ground. We know it makes our work explanatory and look forward to investigating the tinkerable aspects too.

Portal Launch (9 of 12)

We announced the general availability of new committer nominations on the MyFoundation portal one week ago today. Today I'm watching three new candidates inch their way to committerdom from my vantage point as a Technology PMC member:


First, notice that these are real people, not just the personas we use in testing. That's because this is the real portal, not screen shots from test cases.

Second, notice that all three nominees are marking time waiting for five remaining days of the voting period to pass. The vote seems like a done deal with seven +1 already and not even one abstention. What are we waiting for? We're waiting for five more people to notice that there is an election and that they are ensured an opportunity to judge. We're waiting for five more votes or five more days, which ever comes first. These votes don't have to be +1 for us to know that the voters have considered the nomination. Five abstains would push each of these elections forward.

Third, notice that each election gets its own component. This wasn't always the case. An early design had top-components and sub-components just so multiple elections could share a single item on the screen. I argued against this. The distinction was doubling interfaces inside the portal. We reasoned about this just long enough to realize that we could merge similarly titled components in a post processing step. I'm feeling the pressure to do that soon. But the natural place to do it would be in portal.php, in parallel to, and independent of, our swim.php testing framework. That means, eventually, components will look different in test and in production. So long as that difference is systematic I'm not going to worry. We'll all learn the system soon enough.

We were in production for one day before we got a report that our portal had broken. What? A bug slipped through our testing gauntlet? Well, um, yes. Here's how.

The portal talks to three different databases. For convenience in development we throw all of the sample tables into one instance of mysql. Even in staging we just use one mysql instance for running automatic tests. Staging does have three copies of production databases that we use interactively but we can't test everything interactively every release. Our bug was that we were looking for tables in the wrong db. We turned another rev of the portal Saturday morning and still had time for brunch. (Kudos Karl for finding and fixing this.) On Tuesday we added an SQL table usage validator that will catch this class of bug even when all the tables are in one place. We don't expect to be caught by this mistake again.

Portal Requirements (10 of 12)

We had two issues show up on the launch week of the MyFoundation portal. One, a coding error, was explored in part 9 of this series. We'll now examine the other, a requirements omission on our part.

Ed Merks was the first to point out that some of the older or larger projects nominate committers based on components, something we didn't yet capture in our records. Bjorn wrote this up as bug 177087 on Monday, offered an implementation approach on Tuesday, coded it up on Thursday, and Karl rolled it into production on Friday. The fix is to offer a component drop-down on the nomination screen.



This is a non-trivial fix because it touches lots of steps for lots of different roles. For example, the component now shows on status views where it makes a difference.


This is exactly the sort of fix that creep into any system. It is how systems learn. It is also the sort of change that large system designers hate because they can't assess the impact. I asked Bjorn if there was anything scary about chasing the implications of this change through our system. Nope, it was business as usual.

I've consulted to insurance companies that tell me it takes 18 months to add a field to their database. I've also watch those companies' executives' jaws drop when they watch Smalltalk add a field to a running program. These aren't the same thing, of course, but it shows what those executives want.

We're coming to the close of a long series about the MyFoundation portal. I've described the architectural and operational decisions we've made. These are important decisions, not because we couldn't do it a dozen other ways, but, because we've done it exactly the way large, long lived, enterprise systems should be done. Our needs are modest, but then, so are our resources. This lead us to a portal with an enterprise architecture build on principles I've spent a lifetime learning.

Portal Process Process (11 of 12)

In part 10 we argued that important requirements will be discovered in the course of using the MyFoundation portal. We will look to bugzilla for management of this activity. We also anticipate coordinated efforts to create specific portal capabilities and have a process suggestion, the Portal Process Process, for moving such efforts forward.

The process begins by asking stakeholders to sketch both the business value and use cases to be supported by a development. This is enough to merit a wiki page that will evolve with the project. Here is an example, the page we created for the "Question of the Week" poll recently introduced on the portal. It included the following use case sketch and three more.

• a committer will be presented with a new poll question each week
• he/she makes one selection. on a five step scale of disagree to agree, and submits choice.
• choice view is replaced with instant results as bar graph
• bar graph updates (with each refresh) as others complete the week's poll

This workflow called for a new portal component. This was hand drawn on index cards which were later scanned in. Here is one of three views the component would offer.


This design turned into the following component shown here with 47 responses wired in as test data.



You can see that some navigation confusion was resolved and the bar chart bars turned into five pools of dots, one for each response. Larger dots show where responses include additional comments. Roll your mouse over these to see what the respondent said (another use case).


This last screen shot is from the production portal where there is a committer poll in progress.

The portal polling process wiki page goes on to discuss two more use cases involving committer suggested questions and their scheduling for available weeks. It closes with deployment considerations and a roll out plan that calls for a broadcast announcement after about a month of early adopter usage.

Portal Retrospective (12 of 12)

I've argued that the MyFoundation portal is both valuable and innovative. I hope you are convinced. In this closing post of the series I will look back on four additional attributes we sought and then judge how well we've done. Before we even started we identified that our portal must be:

1. Comprehensive: The mechanisms will be sufficiently powerful, general and well developed such that they will be the first choice for all automation of foundation collaborations.
   
2. Compelling: Human interaction will be sufficiently straightforward, useful and attractive such that users, customers and foundation staff, will prefer the system to alternative means to complete a task.
   
3. Compliant: Schema, frameworks, tools and practices will be sufficiently flexible such that unanticipated requests can be addressed, if not completely resolved, with visible improvement within a week.
   
4. Cost-effective: The additional staff burden to maintain the system shall be such that the cost in staff hours to implement any given increment of functionality will be repaid in staff hour savings or corresponding improved service within one year.

Of these four "C"s, I feel best about 1 and 3. Our agile method yields flexibility which, over time, yields power. I'm less sure of 2 and 4. These goals are in tension. One wants to make interfaces beautiful but this isn't cost-effective. We're hoping simplicity will serve us well both ways but will have to wait to see how our choices work out.

What can we expect in the future? More portal components, that is for sure. We also hope that our work will have an impact on the agile community. Agile testing expert Elisabeth Hendrickson has included our work in her tooling wish list. I would like to see a variation of swim.php cooked up for RCP applications. If you have ideas how this might work, talk to me. I know the capability would return even more value in a cross-organization service architecture, though implementation will be even trickier there. Can it be done? Please tell me.

I'll close with one more thought. Online forms have too much in common with income tax forms. Nobody likes filling out either one. Each is a sea of fields, each field another question, one question after another. It is like being interrogated. Can we make filling out a form more like a conversation than an interrogation? The portal's explore links suggest a way toward this goal. These links let you ask a question every now and then. You get to ask, "why do you ask?" Wouldn't it be great if you could always do that?