Project Milestones for Jira

Project milestone page with milestone list
Create project milestone dialog
Add issues to milestone - either manually or automatically based on due date
Issues mapped to milestone
Issue panel to show project context (milestone)

Inspiration

Jira projects can be split up into smaller pieces, e.g. by using components, releases, grouping of issues in epics or, for short-time planning, using sprints to get stories and features implemented. However, if you use components, you don’t have the ability to plan any dates. For releases, you can plan start and release date though. But you don’t have releases in all projects and sometimes they are more fine-grained than necessary. What about the larger phases/steps in a project? What about projects which don’t have components or releases (either because they are team-managed, or if they don’t have anything to do with software development)?

Imagine you have a large project running for several years. Of course, you can summarize issues in epics and plan stories in sprints. But sprints usually have a length of 2 weeks. What about the long-term goals and steps that needed to be achieved during the project?

With our submission for Codegeist 2022, we wanted to provide an app that is providing this long-term planning in large Jira projects. A planning that splits up a project into several smaller phases/steps to get a better overview of the project completion instead of just having a collection of issues that might be grouped in Epics but nothing beyond that.

All that should be achieved with simplicity, an app easy to understand and easy to use for everyone. No need to draw complex Gantt charts in the first place or adding additional issue hierarchies, just keep it as simple as possible. Furthermore, no limitations regarding project type. It can be used in agile software development projects as well as in non-agile business projects. You might think of waterfall project planning when you hear the word milestone. However, that is not the intention here. As said above, also agile scrum projects where sprints are planned, might need a long-term planning if they run for a longer time.

What it does

The project milestones app adds a project page to each project in Jira where users can split up their project into smaller pieces called milestones. Milestones can be described with title, description, (planned) start- and completion date.

Issues from the project can be mapped to the milestones and thus, it can be defined which issues have to be resolved to get the whole milestone done. If all issues mapped to a milestone are resolved, it can be marked as completed. The mapping of issues works in each milestone either manually by selecting issues from the project, or automatically based on the issues due date. As an example, if the start date is January 1st and planned completion date January 31, all issues with a due date in January can be mapped automatically in one action and doesn’t have to be selected manually.

When looking at an issue, you can optionally display the project context, meaning an additional panel that shows if the issue is linked to a milestone or not. If not, and if milestones exist in the project, you can map the issue to the milestone directly in the issue panel. Of course, you can also change or delete the milestone in the issue view.

The app is not limited to either company- or team-managed projects. It can be used in all projects in Jira regardless which type.

How we built it

We built the app with Forge custom UI using the project page module to add the page for the project milestones and the issue panel module to display the project context information on Jira issues. For storage of the project milestone list, we used the properties API. It is called from the frontend and creates or updates the list in the Jira project. When the project page is opened, we check if a list exists in the project, read and display it.

We used modal dialogs with AtlasKit forms and fields for milestone creation, update, and issue mapping. On the issue view, we also read the project list using the properties API and display the respective milestone if the current issue is mapped to it.

Challenges we ran into

It was the first app for us we built from scratch. So far, we only did migration of existing server apps, first with Forge UI kit, then from UI kit to custom UI. We already had an existing concept and a running app there and so we could “copy” it step by step in Forge.

For this project, we started with a blank page and needed to arrange all the items, forms, and fields we wanted to display. Just adding them randomly to the page didn’t work out in the beginning as it looked weird, and the scrolling behavior was really strange. It was a challenge to fix the UI and to get a clean display of the milestones in a project. We had to get familiar to styled components and the different attributes to get to a working frontend which looks nice.

Another challenge was the combination of more than one Forge module in a single app using custom UI. At first, we just duplicated the static resource folder (where the project page was defined) and linked it to the second module (issue panel). It looked fine when we loaded an issue for the first time. All items have been displayed. However, when we clicked on a button, nothing happened. There should be a modal dialog displayed which is triggered by a useState hook which changes the value of a variable in our code. Unfortunately, this didn’t work in the second module. After searching for a solution in the developer community, we realized that it is not possible to have 2 modules in one app with just a duplication of the frontend code. Instead, we had to implement a top level file that reads the context we are in (either project page or issue panel) and then loads the respective code from one static resources folder, which is the only source for our frontend code.

Finally, also the management of npm packages and dependencies became a challenge for us. Whenever we added a new package, it was displayed that there are several (more than 30) vulnerabilities with high severity. Running npm audit fix resolves only a few of them. As recommended, we also tried to run npm audit fix --force which resolved even more. However, afterwards our app didn’t load at all and was broken. This worried us as we didn’t want to have an app which is running fine, but which isn’t secure. After searching for a solution on the internet, we found that we weren’t the first developers with such concerns. Many others had the same issue and questions before. After reading more about it, it became clear that many of those vulnerabilities were only npm internal ones which don’t affect the packages we need for our app. Furthermore, if we run npm audit -production, there are no vulnerabilities displayed, which shows us that for productive use, everything is fine.

Accomplishments that we're proud of

We built our first Forge app with custom UI from scratch. No migration of an existing app and no predefined concept we just needed to adapt. We are proud we achieved that in a short period of time with a small team of only 2 people.

We are proud of finding solutions to all the challenges (see above) and little problems we ran into. Even as we already have developed 3 Forge apps for the Atlassian Marketplace, we learned a lot (see below) and are confident we can find good solutions to any problems we might face in the future. Even if there are still limitations in Forge, we are proud to have accomplished the development of several apps, which work well and which provide all features we wanted to include.

What we learned

Some of the things we learned have already be mentioned above. Therefore, we want to provide a complete list with bullet point in this section. What we learned:

Usage of styled components to define a nice-looking UI with Forge custom UI
Including more than one module in a Forge app
Learned about the numerous possibilities and flexibility of custom UI (especially compared to UI kit)
Implementation of project page forge module
Usage of useState and useEffect hooks
Tunneling for a custom UI app (different than we know it from UI kit)
npm package management and dealing with vulnerabilities

What's next for Project Milestones for Jira

Forge custom UI opened up so many new possibilities for us and we have many ideas for additional features. Project Milestones for Jira in its current status is only the starting point for a lot of features that are still to come. Our first goal now is to bring the app to market, so publish it on the Atlassian Marketplace. Furthermore, we think of the following new features for the future: