CONTRIBUTING

Unified home is a single page application that delivers a dynamic landing page for any application on Unified Shell. Unified Home uses the Quarry dashboard framework, leveraging widgets that can be contributed by any application team. Examples of applications implementing their home experience through unified home include Experience Cloud home (/home) and Journey Optimizer home (/journey-optimizer/home). The internal name for Unified Home is Pueblo. Widgets that are used in unified home applications live in this folder, /src/widgets. The following contribution guide describes the process for both adding a new widget and making modifications to an existing widget.

1. What is a Pueblo Widget?

A Pueblo widget is a UI component that is delivered by the Pueblo application for any home experience. It provides value to the end user by ensuring that their landing experience is relevant and efficient, such as by providing faster ways to jump into work, the ability to view recent activity and the delivery of learn content from Experience League. A pueblo widget should fit into the quarry dashboard framework, meaning that it should be wrapped in a quarry dashboard widget and adhere to the spectrum design guidelines for widgets.

The recommended approach to widget creation is to contribute your widget to the widgets folder in this repository. However, if your widget needs to be used in multiple places, @quarry-connected may be a better choice. Contributing a widget to @quarry-connected gives your widget DXUE visibility and means that the widget can be used by both unified home and any other application that may need it.

2. Why use Unified Home?

A good home experience can transform how a customer uses your product. It can help a user to jump back into their work where they left off, figure out where to start when they receive access to a new product, or learn about product features and upcoming adobe events. Leveraging pueblo means that apps can avoid duplicative work to create a home page and ensure a uniform look and feel to other experience cloud applications.

Interested in leveraging unified home? Set up a meeting with @doten @symanovi and @sgould to discuss your use case.

3. List of Related Repositories

• https://git.corp.adobe.com/exc/pueblo - Contains the code for the home application which runs at multiple routes (/home, /journey-optimizer/home). Widgets live here in src/widgets
• https://git.corp.adobe.com/frontend/quarry - Pueblo follows the spectrum dashboard pattern. Quarry contains the dashboard framework leveraged in pueblo.

4. Developer Setup

1. Join the #pueblo Slack channel.
2. Clone the pueblo repository.
3. Setup your local dev by following the steps here.

5. Developing - Creating a new home page

Creating a new home page using pueblo requires adding a new config to unified-shell. Your apps home page configuration should inherit from the pueblo base.

The minimum configuration required to get a pueblo app up and running locally looks like this:

import {puebloBaseConfig} from './pueblo';
import {Solution} from '@exc/core/src/models/Solution';

const myAppsConfig: Solution = {
  ...puebloBaseConfig,
  name: 'My Apps Name',
  appId: 'my-app-id',
  path: 'my-app/home'
}
export default myAppsConfig;

Consult the unified shell docs for more information about configurations. Specifically this section describes how to run a config locally that hasn't been merged yet.

Add an entry my-app-id: [] here and run pueblo locally and you should see a blank home page rendered at your route with the welcome message. Time to add some widgets!

6. Developing - Contributing a widget

New widgets that will be used by pueblo should live in widgets folder within pueblo.

To speed up the development process, we've included a script to generate the minimum files required for a new widget.

yarn generate

The script will prompt you for the name of your widget and autogenerate files for your widget in the src, tests, and docs folders. In the src folder yarn generate creates 2 files, YourWidgetName.tsx and index.tsx. YourWidgetName.tsx should contain the code for your widget. index.tsx should lazy load the widget and export a function that makes any calls for props your component needs before it dynamically renders the widget.

To get your widgets rendering on a home page import your "get widget" function here and add it to the list of widgets corresponding to your app id here.

Tips

1. You should only make async requests before rendering the widget if the widget conditionally hides. Otherwise, render the widget with a spinner or ghost loader and then show content as it becomes available.
2. If you need to share classes across components, consider making the class a singleton so multiple widgets don't instantiate the same class.

7. Coding Guidelines

• File a JIRA ticket associated with your widget containing a detailed description of the task, relevant epic links, and documentation links. If it is a bug, clearly outline the steps to reproduce it.

• All code changes should:

  • Adhere to our lint by running yarn lint.
  • Be accessible (meets all WCAG 2.1 standards) and pass a run by the AXE plugin in the browser.
  • Be internationalized (localized into all languages that Unified Shell supports). It is preferred that the widget use intl-react over adobe-intl-react along with aladdin.
  • Support both light and dark themes, as switched from the profile menu in the Unified Shell. This is only mandatory if the application you are building a home page for supports both light and dark theme.
  • Include >=90% test coverage.
  • Use @adobe/exc-app to log metrics to EIM including error information.
  • Include appropriate documentation updates.
  • Be performant (see #10.3)
  • Increase the overall bundle size by a reasonable amount. All widgets should be lazy loaded and related services should be dynamically imported so that the bundle size grows marginally.
  • As a rule of thumb, widgets should show useful content to the user. If your widget has no content (i.e. it displays recent activity and the user has none), include a call to action (button or link) or hide the widget until it has content. Double check your widgets empty state with @sgould (PM for unified home) to ensure it is consistent with existing patterns.

• Once you have created a new widget or made a change that adheres to these code standards, issue a pull request for your changes. Make sure the pull request title matches the "JIRA-ID: JIRA ticket title."

• Code reviewers will be automatically assigned to your PR. You are encouraged to tag any additional repository maintainers via the github @name notification mechanism.

8. PR Review Process

The pueblo team (@symanovi @doten) are the codeowners of the pueblo repository, and therefore, an approving review is required before any code can be merged. That being said, a member from your scrum team should always review and approve the pull request first.

If you have added a new widget, you should edit the codeowners document with the path to your component, i.e. /packages/src/widgets/my-widget @team-for-my-widget

9. Deploying your widget

Once your widget is merged to the pueblo repo, it will immediately be available on qa and stage. Pueblo deploys to production on Thursday afternoons in conjunction with Unified Shell.

10. Tests

10.1. Unit Tests

As a contributor, it is your responsibility to add new tests for your feature. Test coverage for pueblo should not dip below 90%.

10.2. Integration Tests

If your application's home page is not yet live on pueblo, you can skip this section. Integration tests for pueblo are written in cypress and leverage spa-pipeline's automation framework. They are run against experience-stage. The tests live in the pueblo repo and test the home pages and widgets of applications running on pueblo. Once your widget has been added to a home page, it is up to you to write integration tests that test the widget. To run integration tests against localhost change this line https://git.corp.adobe.com/exc/pueblo/blob/main/cypress.json#L2 and run yarn cypress:open.

10.3. Performance

Widgets should be built in a way that optimizes performance and avoids a cumulative layout shift on load. If your widget needs to make network calls, build the widget in such a way that it will not block the page load (i.e. ghost loading or add a spinner/loading state to the widget). If your widget needs to block page load entirely (e.g. the widget conditionally shows based on a network call), discuss with the #pueblo team what the best options are.

To avoid a performance hit for slower loading widgets, Unified shell can prefetch the data and pass it to the widget via the optional data prop. This allows the data to be fetched as soon as shell has the essential information to make a network call (such as user profile and ims token). Since we cache prefetched data, it should be available even quicker on subsequent page loads. Contact a #pueblo team member to pursue this option.

11. Monitoring

Synthetic checks in New Relic monitor the health of this service. When your application goes live on pueblo, you should work with a #pueblo team member to ensure that scripts are added to New Relic to monitor the availability of your widgets and home page.

12. Production Support

PR reviews and test automation are expected to catch most of the issues with your change. However, by experience, we know that every new change will bring potential instability to the service. The unified shell team will be on-call for pueblo and it is possible the on-call engineers may not be fully aware of your change. In case of a production issue or a CSO, contributors agree to support the on-call engineers when the problem is likely related to their change. To help facilitate this coordination, please fill out the "CSO" section of your documentation page with the contacts and procedure if your widget breaks in production.

13. Documentation

Documentation lives in the docs folder. If you use yarn generate a docs mdx file will be created for your widget automatically. Otherwise, please add a file to the docs folder with an overview of the widget.

14. Support For the Contributors

If you need help, please ask your question in the #pueblo slack channel or reach out to the code owners yourself. If your question is better asked in person, please join the Unified Shell office hours on Thursdays at 9AM PST. Reach out in #unified-shell if you need to be invited to the meeting.

15. Contribute to Improve CONTRIBUTING.md

This is a live document. Suggestions, improvements to the guidelines, processes outlined here are always welcome! Please issue a pull requests to make changes to this document.