Contributing to Product Central Reference Architecture Templates

Getting Started

Fork the Repository

Begin by forking the main repository located at 99x/product-central-architectures. This creates a personal copy of the repository under your GitHub account.

Clone the Repository

Clone your forked repository to your local machine using the following command:

git clone https://github.com/your-username/product-central-architectures.git

Replace your-username with your GitHub username.

Adhering to the Folder Structure

Ensure that you follow the prescribed folder structure. All contributions should be developed within the github/ folder path. Refer to the aws-fullstack-app template as a primary example. Consistency in structure helps maintain clarity and organization across all contributions.

Creating Content

Code Placement: Place all code files within the content folder.
Catalog Information: Declare the Product Central (PC) component within the catalog-info.yaml file. Follow the template format provided below.
Template Definition: Define the scaffolder template in the template.yaml file using the example provided below.
Updating Showcase Templates: Update the RA's path in the showcase-templates.yaml.

Example `template.yaml`:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: aws-fullstack-app
  title: AWS Fullstack App
  description: Fullstack App deployed in AWS
  annotations:
    backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/aws-fullstack-app
    backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/aws-fullstack-app
  tags:
    - aws
    - full-stack
    - nextjs
    - nestjs
    - micro-frontend
    - nx
    - module-federation
    - server
    - infrastructure
    - reference-architecture
  links:
    - url: https://github.com/99x/product-central-architectures
      title: 99x Product Central Architectures
      icon: dashboard

spec:
  owner: user:99xadmin
  type: service

  parameters:
    - title: Provide information about the component
      required:
        - name
        - repoUrl
        - description
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
          ui:autofocus: true
          maxLength: 50
          pattern: "^[a-zA-Z0-9-]*$"
          ui:help: "Hint: Name should only contain alphanumeric characters and hyphens"
          ui:options:
            rows: 5
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com
        description:
          title: Description
          type: string
          description: A brief description of the component and its purpose
          ui:options:
            rows: 5

    - title: Provide information about applications
      required:
        - coreAppName
        - remoteAppName
        - serverAppName
      properties:
        coreAppName:
          title: What would you like to name the client core application?
          type: string
          description: The name of the client core application
          maxLength: 50
          pattern: "^[a-zA-Z0-9-]*$"
          ui:help: "Hint: Name should only contain alphanumeric characters and hyphens"
          default: core
        remoteAppName:
          title: What would you like to name the first client remote application? (You can always add more remote applications later)
          type: string
          description: The name of the genesis client remote application
          maxLength: 50
          pattern: "^[a-zA-Z0-9-]*$"
          ui:help: "Hint: Name should only contain alphanumeric characters and hyphens"
          default: remote
        serverAppName:
          title: What would you like to name the server application?
          type: string
          description: The name of the server application
          maxLength: 50
          pattern: "^[a-zA-Z0-9-]*$"
          ui:help: "Hint: Name should only contain alphanumeric characters and hyphens"
          default: server

    - title: Provide information about the deployment environment and credentials
      required:
        - project
        - environment
        - awsRegion
        - awsAccessKeyId
        - awsSecretAccessKey
        - bucketName
      properties:
        project:
          title: Project
          type: string
          description: Specify the project name for AWS resources
          maxLength: 50
          pattern: "^[a-zA-Z0-9-]*$"
          ui:help: "Hint: Name should only contain alphanumeric characters and hyphens"
        environment:
          title: Environment
          type: string
          description: Choose the environment to deploy to
          enum:
            - dev
            - demo
            - prod
          default: dev
        awsAccessKeyId:
          title: AWS Access Key ID
          type: string
          description: The AWS access key ID to access the AWS resources
          ui:field: Secret
        awsSecretAccessKey:
          title: AWS Secret Access Key
          type: string
          description: The AWS secret access key to access the AWS resources
          ui:field: Secret
        awsRegion:
          title: Default Region
          type: string
          description: The default region to deploy the application
          enum:
            - us-east-1
            - us-west-1
            - us-west-2
            - eu-west-1
            - eu-west-2
            - ap-southeast-1
            - ap-southeast-2
            - ap-northeast-1
            - ap-northeast-2
          default: ap-southeast-1
        bucketName:
          title: S3 Bucket Name
          type: string
          description: The name of the S3 bucket to store the Terraform state file
          default: client-bucket

  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./content
        copyWithoutTemplating:
          - "**/.github/**"
          - "./**/.github/**"
        values:
          name: ${{ parameters.name }}
          slug: ${{ parameters.repoUrl | projectSlug }}
          description: ${{ parameters.description }}
          coreAppName: ${{ parameters.coreAppName }}
          remoteAppName: ${{ parameters.remoteAppName }}
          serverAppName: ${{ parameters.serverAppName }}

    - id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: ${{ parameters.description }}
        repoUrl: ${{ parameters.repoUrl }}
        repoVisibility: private
        defaultBranch: main
        gitAuthorName: 99xproductcentral
        gitAuthorEmail: [email protected]
        secrets:
          AWS_ACCESS_KEY_ID: ${{ parameters.awsAccessKeyId }}
          AWS_SECRET_ACCESS_KEY: ${{ parameters.awsSecretAccessKey }}
          AWS_REGION: ${{ parameters.awsRegion }}

    - id: github-action
      name: Provision Infrastructure
      action: github:actions:dispatch
      input:
        workflowId: "init-infra.yaml"
        repoUrl: ${{ parameters.repoUrl }}
        branchOrTagName: "main"
        workflowInputs:
          parameters: ${{ parameters | dump }}

    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: "/catalog-info.yaml"

  output:
    links:
      - title: Repository
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: Open in catalog
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}
      - title: CloudFront Distribution ID
        url: ${{ steps['github-action'].output.cloudfront_distribution_id }}

Example `catalog-info.yaml`:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name | dump }}
  annotations:
    github.com/project-slug: ${{ values.slug }}
    backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/99x-design-system
    backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/99x-design-system
  description: ${{ values.name }} is a design system that is used to build user interfaces for 99x products.
  tags:
    - storybook
    - design-system
    - reference-architecture
  links:
    - url: https://github.com/99x/product-central-architectures
      title: 99x Product Central Architectures
      icon: dashboard
spec:
  type: service
  owner: user:99xadmin
  lifecycle: production
  system: productcentral

Annotations

Ensure to use the following annotations in your template.yaml and catalog-info.yaml:

backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/<app_name>
backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/<app_name>

Refer to the formats of the documentation from the following examples:

TechDocs: aws-fullstack-app
ADR: aws-fullstack-app

Writing Documentation

Comprehensive Documentation: Use TechDocs to write thorough documentation explaining the template's purpose, usage, and any other relevant information. This documentation should be clear and concise to assist other contributors and users.

Writing Decision Records

Architectural Decision Records (ADRs): Document all architectural decisions using mkdocs. ADRs provide a structured format to capture the rationale behind technical choices, ensuring transparency and clarity.

Testing the Template

To test the scaffolder of the template, login to Product Central application, go to the[Template Editor] section (https://app.productcentral.io/create/edit) and choose Edit Template Form.

Committing and Pushing Changes

Commit Changes: Once your changes are ready, commit them to your local repository.
```
git add .
git commit -m "Your detailed commit message"
```
Push Changes: Push your commits to your forked repository.
```
git push origin main
```

Raising a Pull Request (PR)

PR Submission: Navigate to the main repository and raise a Pull Request (PR) from your fork. This notifies the repository maintainers that your contribution is ready for review.

PR Review Process

Review by Leads: The repository leads will review your PR.
Approval: If the PR meets the standards, it will be merged into the main branch.
Changes Requested: If changes are requested, address the feedback and push the updated changes to your fork.

Completion

The contribution process is completed once your PR is merged into the main branch of the 99x/product-central-architectures repository.

By following these steps, you can ensure a smooth contribution process that aligns with the standards and practices of Product Central. Your contributions are valuable and appreciated in enhancing the overall architecture templates.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Product Central Reference Architecture Templates

Getting Started

Fork the Repository

Clone the Repository

Adhering to the Folder Structure

Creating Content

Example `template.yaml`:

Example `catalog-info.yaml`:

Annotations

Writing Documentation

Writing Decision Records

Testing the Template

Committing and Pushing Changes

Raising a Pull Request (PR)

PR Review Process

Completion

Clone this wiki locally

Contributing to Product Central Reference Architecture Templates

Getting Started

Fork the Repository

Clone the Repository

Adhering to the Folder Structure

Creating Content

Example template.yaml:

Example catalog-info.yaml:

Annotations

Writing Documentation

Writing Decision Records

Testing the Template

Committing and Pushing Changes

Raising a Pull Request (PR)

PR Review Process

Completion

Clone this wiki locally

Example `template.yaml`:

Example `catalog-info.yaml`: