ROSE Compiler Framework/Workflow

Motivation and Goals

The goal of the ROSE workflow is to have a streamlined, simplified, and automated process to allow users and developers to:

• Improve the quality of ROSE source code and documentation
• improve our productivity allowing us to produce high quality work using less time and other resources than would otherwise be required

Development Guide

Developing a big, sophisticated project entails many challenges. To mitigate some of these challenges, we have adopted several best practices: incremental development, code review, and continuous integration.

• Iterative and Incremental software development for early results, controllable risks, and better engagement of stakeholders
• Code review for consistency, maintainability, usability, and quality
• Continuous Integration for automated testing, easy release, and scalable collaboration

Incremental Development

Developing new functionality in small steps, where the resulting code at each step is a useful improvement over the previous state. Contrast to developing an entire feature fully elaborated, with no points along the way at which it's externally usable.

Each ROSE developer is expected to push his/her work at least once every three weeks.

Major benefits of doing things incrementally

• You can have intermediate results along the path. So your sponsors will sleep better.
• You will get feedback early and frequently about if you are heading to the right direction.
• Your work will be tested and merged often into the master branch, avoiding the risks of merge conflicts.

See more tips about How to incrementally work on a project

Code Review

See Code Review in ROSE.

Continuous Integration

Incorporating changes from work in progress into a shared mainline as frequently as possible, in order to identify incompatible changes and introduced bugs as early as possible. The integrated changes need not be particular increments of functionality as far as the rest of the system is concerned.

In other words, incremental development is about making one's work valuable as early as possible, and potentially about getting a better sense of what direction it should take, while continuous integration is about reducing the risks that result from codebase divergence as multiple people do development in parallel.

The question of whether to conditionalize new code is an interesting one. By doing so, one narrows the scope of continuous integration to just checking for surface incompatibilities in merging the changed code. Without actually running the new code against the existing tests, the early detection of introduced bugs is lost. In exchange, multiple people working in the same part of the codebase become less likely to step on each other's toes, because the relevant code changes are distributed more rapidly.

See more at Continuous Integration

High Level Workflow

Requirement Analysis

External:

• External (https://github.com/rose-compiler/rose): start an issue to be discussed
• Wikibook:
  • collect community input
• mailing list: interaction with users, feel users' need

Internal: Need LC accounts to access

• JIRA: https://lc.llnl.gov/jira
  • Email interface: send to : rose-bugs@llnl.gov, cc' to assignee
• Confluence: https://lc.llnl.gov/confluence/

Design

• Wikibook: community-based design documents and provoke discussion
• Powerpoint slides: more formal communication about what is the design
• Confluence: https://lc.llnl.gov/confluence/

Implementation

• Redmine (http://hudson-rose-30:3000/): create projects based on milestones and user input, create and track tasks
  • Project-Specific Tasks
  • Private Issue Tracking
  • Private Documentation
    • Using redmine's wiki
• Github:
  • Internal (http://github.llnl.gov/): for code review only,
  • External (https://github.com/rose-compiler/rose): public hosting code, public issue tracking for general ROSE bugs and features.
  • "Rosebot" to automate Github workflow: preliminary testing, policies (git-hooks), automatically add reviewers, etc.

Testing

• Jenkins ((http://hudson-rose-30:8080/)): continuous integration of new features, bugfixes
• https://rosecompiler1.llnl.gov:8443/jenkins-edg4x/ New Jenkins instance for EDG 4.x branch work

Documentation

• See more at ROSE Compiler Framework/Documentation

Publicity

• Website (http://www.rosecompiler.org): content management system hooked up with all other components

Proposing Workflow Changes

Major workflow improvements and changes should be thoroughly tested and reviewed by staff members before deployment since they may have profound impact on the project

How to propose a workflow change

• Submit a ticket on github.com's rose-public/rose issue tracker. In the ticket, provide the following information:
  • What is it: Explain what change is proposed
  • Why the changes: the long-term benefits for our productivity and quality of work
  • The cost of the changes: learning curve, maintainability, purchase cost

Reviewing Workflow Change Proposals

Review criteria

• Optimize
  • Optimize our workflow to allow us to do more quality and use less time and other resources.
  • Address what is slowing us down or distracting us.
  • Simplify daily life. Compare how we can eliminate or automate using the proposed workflow improvements.
    • It is counterproductive to improve workflow by adding more hoops/steps/clicks into daily work.
• Improve:
  • Allows the improvement of the quality of work incrementally:
  • Accepting incremental improvements is more realistic than asking for perfection in the first try.
  • Workflow should allow quick new contributions and fast revision of existing contributions
• Automate:
  • Additions to the workflow should be automated as much as possible.
• Preserve:
  • It must preserve existing work:
    • No creation of anything from scratch
  • Does it interact well with existing workflow
  • Is there a way to convert existing code/documents into the new form
• Simplicity:
  • The more software tools we depend on, the harder to use and maintain our workflow. Similarly, the more formats/standards we enforce, the harder for developers to do their daily work
  • Adopting new required software components and new required technical formats/standards in our workflow should be very carefully reviewed for the associated long-term benefits and costs. Long-term means the range of 5 to 10 years and is not tied to a temporary thing we use now.
• Preference of major contributors: Whoever contributes the most should has a little bit more weight to say
• Documentation: We require major changes to be documented and reviewed before deployment. Writing down things can help us clarify details and solicit wider comments (instead of limited to face-to-face meeting)