MOJ Frontend Component Review: Streamlining Submissions

by Alex Johnson 56 views

This document outlines the review process for experimental component submissions within the ministryofjustice/moj-frontend project. It details the steps, responsibilities, and criteria for evaluating new components before they are released. The specific component under review is the "test component," and this document serves as a guide for the review team to ensure quality and adherence to standards.

Submission Details

1. Initial Review

The initial review phase focuses on gathering feedback and identifying potential issues with the submitted component. This involves both individual asynchronous reviews and a collaborative discussion to consolidate findings.

  • Screenshot and Miro Frame: @helennickols will add a screenshot of the component preview to a Miro frame on the review board. This visual representation helps the team quickly grasp the component's appearance and functionality. This step is important for providing a central point of reference during the review process, allowing reviewers to easily compare the component to its intended design and usage. The screenshot should accurately reflect the component's current state and highlight any key features or potential areas of concern. It's crucial that the image is clear and well-composed to facilitate effective feedback. Consider things like proper sizing, appropriate contrast, and the inclusion of relevant context within the image. Furthermore, the Miro board should be easily accessible to all reviewers and organized in a way that promotes efficient collaboration. This might involve using specific sections for different aspects of the review, such as accessibility, code quality, or visual design. Remember, the goal is to create a shared understanding of the component and to streamline the feedback process.
  • Async Review: @helennickols, @murrlipp, and @chrispymm will conduct asynchronous reviews, adding comments on stickies within the Miro board. This allows each reviewer to examine the component independently and provide detailed feedback at their own pace. The stickies should be specific and actionable, clearly outlining any issues or suggestions for improvement. It is beneficial if each feedback note explains the rationale behind the feedback. This async process is crucial to allow team members to carefully assess the component based on their expertise.
  • Weekly 30min Call: @helennickols, @murrlipp, @chrispymm, and @asma-ban will participate in a weekly call to review the asynchronous comments and define any queries for the contributor. This collaborative discussion ensures that all feedback is considered and that a unified set of questions is formulated. This is the moment to have a meaningful discussion about the component. The goal is to identify any remaining uncertainties or areas where further clarification is needed from the contributor. The call should be structured to ensure that all reviewers have an opportunity to voice their opinions and contribute to the discussion. Effective communication and active listening are essential for a productive review. Prioritize addressing the most critical issues first and allocating time for a thorough discussion of each point.

2. Decision Point

Following the initial review and discussion, a decision must be made regarding whether the component meets the required criteria for inclusion in the moj-frontend library.

  • Rejection: If the component does not meet the criteria, the contributor will be contacted with a clear explanation of the reasons for rejection. The weekly call will determine who is responsible for contacting the contributor. It's important to provide constructive feedback that helps the contributor understand the shortcomings of the component and potentially improve it for future submissions. Clearly and concisely outlining the reasons for rejection, citing specific criteria that were not met is important. Ensure the communication is professional and respectful, even when delivering negative news. Being transparent about the evaluation process and providing opportunities for the contributor to ask questions can help maintain a positive relationship and encourage future contributions.
  • Acceptance: If the component does meet the criteria, the review process will proceed to section 3, which focuses on addressing any remaining queries.

3. Queries (if any)

This section addresses any outstanding questions or requests for clarification that the review team has for the component contributor.

  • Queries for Contributor: If there are queries, the contributor will be contacted with a detailed list of questions. The weekly call will determine who is responsible for contacting the contributor. These queries should be specific and actionable, providing the contributor with clear guidance on what information is needed. Frame the questions in a way that is easy to understand and avoid technical jargon where possible. The goal is to elicit the information needed to make an informed decision about the component's suitability for inclusion in the moj-frontend library. Consider grouping related questions together to streamline the communication process.
  • No Queries: If there are no queries, the review process will proceed to section 4, which outlines the tasks to be completed before setting a release date.

4. Tasks to be Done Before the Release Date is Set

Before a release date can be set, several tasks must be completed to ensure the component is ready for public use. These tasks are divided among the review team members based on their areas of expertise.

@helennickols:

  • Content: Write a lede and summary and add to the pull request. The lede should be a concise and engaging introduction to the component, while the summary should provide a more detailed overview of its functionality and purpose. These content elements are essential for helping users understand the component and how it can be used in their projects. The content should be written in clear, accessible language, avoiding technical jargon where possible. Focus on highlighting the key benefits of the component and explaining how it solves a particular problem or addresses a specific need.
  • Content: Write release notes and share for feedback. The release notes should document any changes, improvements, or bug fixes included in the component's release. This information is crucial for users who are upgrading from a previous version of the component. The release notes should be clear, concise, and easy to understand. Use bullet points or numbered lists to organize the information and make it easy to scan. Share the release notes with the review team for feedback before publishing them to ensure accuracy and completeness.
  • Image Review: Verify the image is free of confidential data (e.g., prison procedures) and Personally Identifiable Information (PII). Also, confirm the image clearly showcases the component. Image review is vital to protect sensitive information and ensure the component is presented effectively. Check thoroughly that there is no data leak. The image should be well-composed, properly lit, and free of any distractions that could detract from the component itself. If possible, provide multiple images or screenshots to showcase the component from different angles or in different use cases.

@chrispymm:

  • Code Review: Assess the code for quality, adherence to coding standards, and compatibility with the moj-frontend language(s). Ensure the code produces the expected visual output and is free of third-party dependencies and external requests. Code quality must be high. This review is critical for maintaining the integrity and security of the moj-frontend library. Pay close attention to code clarity, maintainability, and performance. Identify potential security vulnerabilities or performance bottlenecks and suggest improvements. The code should be well-documented and easy to understand. Consider using automated code analysis tools to identify potential issues and enforce coding standards.

@murrlipp:

  • Accessibility Review: Confirm that the accessibility comments relate to the component and write appropriate alt text for the contributed image. A11y is key to make the component usable by everyone, including people with disabilities. Alt text should accurately describe the image and provide context for users who cannot see it. The accessibility comments should address any potential accessibility issues and provide guidance on how to resolve them. Use established accessibility guidelines and best practices to ensure the component is fully accessible.
  • Thumbnail Creation: Create a thumbnail image and add it to the pull request. The thumbnail should be a smaller version of the component's image that is used for preview purposes. The thumbnail should be visually appealing and accurately represent the component. Consider using a consistent style for all thumbnails in the moj-frontend library. A good thumbnail is essential to entice users to explore the component further.
  • Figma Integration: Ensure the Figma component matches the image and add the component to the MOJ Figma Kit in a new branch. Figma is important. The Figma component should be a faithful representation of the actual component, allowing designers to easily incorporate it into their designs. The Figma component should be well-organized and easy to use. Consider providing different variations or configurations of the component to meet different design needs. Check the integration well.

5. Set Release Date

Once all tasks in section 4 have been completed, the review team can set a release date for the component.

  • Release Date Agreement: @helennickols, @murrlipp, @chrispymm, and @asma-ban will collaborate to determine a suitable release date. Consider the team workload and any upcoming events or deadlines that could impact the release schedule. The release date should be realistic and achievable. Clearly communicate the release date to all stakeholders.
  • Calendar Integration: @asma-ban will add the release date to the team calendar to ensure visibility and prevent conflicts. Adding the date to the calendar is a basic but efficient step to do. This helps keep everyone informed and ensures that the release is properly coordinated.

6. Tasks to be Done in Order After the Release Date is Set

After the release date is set, a series of tasks must be completed in a specific order to ensure a smooth and successful release.

@murrlipp:

  1. Add the release date to the Figma page. It's important for keeping things in sync. Update the Figma page with the confirmed release date to ensure that designers are aware of when the component will be available. Be sure to double check that date.
  2. Merge the Figma branch. This should not be skipped. Merge the Figma branch containing the new component into the main Figma Kit branch. This makes the component available to all designers using the MOJ Figma Kit. This step must be done before publishing the Figma kit. Triple check before merge.
  3. Add the Figma link to the pull request. Keep the PR updated. Add a link to the Figma component in the pull request to provide a direct connection between the code and the design. This makes it easier for developers and designers to collaborate on the component. Do it right away.
  4. Create a Github discussion and add the link to the pull request. Encourage discussion! Create a Github discussion thread to encourage feedback and discussion about the component. This provides a forum for users to ask questions, report issues, and suggest improvements. Add a link to the discussion thread in the pull request. Promote the discussion.
  5. Publish the Figma kit internally and externally. Publishing is fun. Publish the updated Figma Kit both internally and externally to make the new component available to all users. This ensures that everyone has access to the latest version of the component. Enjoy publishing.

@chrispymm:

  1. Merge the pull request and check deployment. One of the final steps! Merge the pull request containing the component's code into the main branch and verify that the component is deployed correctly. This makes the component live and available for use in production environments. Check if the deployment is actually working.

@helennickols:

  1. Contact the contributor. Reach out to the contributor. Contact the contributor to inform them that their component has been released and thank them for their contribution. Good relationship is important. This helps foster a positive relationship with the contributor and encourages future contributions.
  2. Send release notes. Inform users of the release. Send out the release notes to inform users about the new component and any changes or improvements that have been made. This helps users understand the component and how to use it effectively. Make sure users are informed.

@asma-ban / @robertjmccarthy / @NatashaMcGuireMOJ:

  1. Add the component to the analytics spreadsheet. Measure results. Add the component to the analytics spreadsheet to track its usage and performance. This provides valuable data that can be used to improve the component and inform future development efforts. Analytics are important.

By following these steps, the ministryofjustice/moj-frontend team can ensure that new components are thoroughly reviewed, properly documented, and successfully released.

For more information on accessibility best practices, check out the Web Accessibility Initiative (WAI) website.