Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
310 lines (230 loc) · 10.6 KB

CONTRIBUTING.md

File metadata and controls

310 lines (230 loc) · 10.6 KB

Nova contribution guidelines

Create a branch or use ticket to branch from

We welcome contributions from the community! Here are the steps to contribute to our library:

Internal, Visa users

  • Find the ticket related to the issue you are wanting to solve or create a Jira ticket and provide the necessary information.
  • Create a branch from this ticket using the relevant branch type.
  • Be sure to follow the steps and processes laid out in our CONTRIBUTE.md file and reference the Working in Nova Angular section below to get started.
  • Once the issue is resolved and tests are added, open a PR to development on Bitbucket.
  • Our team will provide feedback and merge it once approved.

External, public users

  • Find the ticket related to the issue you are wanting to solve or create a GitHub issue and provide the necessary information.
  • Fork our repository on GitHub.
  • Clone your forked repository to your local machine.
  • Create a branch from the Github issue you created.
  • Be sure to follow the steps and processes laid out in our CONTRIBUTE.md file and reference the Working in Nova Angular section below to get started.
  • Once the issue is resolved and tests are added, open a PR to our main branch on GitHub.
  • Our team will review your pull request, provide feedback, and merge it once approved.

Thank you for contributing to our project! Your contributions help make our library better for everyone.

Code documentation in Nova workshops

Nova workshops have strict rules for documentation because the documentation found here is also reflected in our Home Experience (HX) site.

  • Work with our Content team as much as possible to create and refine documentation around any components, features, examples, and etc.
  • Wherever possible, code documentation comments should be sentence case. This means it should include a capital first letter and the correct ending punctuation.
  • Component property descriptions should have plural verbs (ie allows, emits, provides)

Working in Nova Angular

Changes to Nova Angular must consider our design, content, and a11y guidelines. All tests should pass and any new features should receive tests as well.

Docs portal

Our documentation portal is located in projects/workshop/src. This is where you will find the examples for each component, directive, and service available in Nova Angular.

Docs portal architecture

  • app
    • components
      • component-name
        • example-name
          • example-files
        • component-page-files
    • foundations
      • foundation-name
        • example-name
          • example-files
        • foundation-page-files
    • services
      • service-name
        • example-name
          • example-files
        • service-page-files
    • utilities
      • utility-name
        • example-name
          • example-files
        • utility-page-files
    • shared
      • shared-app-pages-and-components

For the most part, you shouldn't need to touch the shared pages or components. Notice that each example has it's own folder and is located in the appropriate category. If you add a new example or docs page, you will need to update the relevant routing file*.

*The component routing files are auto-generated by running pnpm generate-routes.

Component library

Our component library is located in projects/nova-angular/src/lib. This is where you will find the library code for each component, directive, and service available in Nova Angular.

Component library architecture

  • src
    • lib
      • _utilities
        • angular-specific-directives
          • angular-specific-directives-files
        • angular-services
          • angular-services
      • component/directive-name
        • component/directive-files
      • Nova lib constants
      • Nova lib module
      • Nova lib service
    • index.ts

All directives and components are standalone and are located in their own folder. All directives and components that are intended for use in Nova Angular should be in both the Nova lib module and the index.ts. Services should only be added to index.ts. Follow the format and comments of the files on how and where to add these items.

Serving the docs app

To view the documentation app, open a terminal and run pnpm watch. Open another terminal and run pnpm start. This will start a local server for the documentation. The system is set up to detect any modifications made to the component library. When changes occur, the browser will automatically refresh and display the updated content without requiring a manual reload. To view API changes in the API tables, run pnpm api.

Committing

This library follows the Conventional Commit specification.

Commit message format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type

Use one of the following. Read here for more semantics and background on each type.

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Scope

In relevance to this repo, the scope could be the component or asset name (eg. avatar), or it could be another relevant item (eg. readme, api).

chore(api): updates signature in dev docs

Description

Prefer to use action verbs and keep the entire line at or below 72 characters. Some examples below.

feat(checkbox): adds simplification to functional logic
fix(radio): removes the double check issue

Body

One or more free-form paragraphs one blank line after the description. We recommend using unordered lists for easy readability.

fix(radio): removes the double check issue

- undoes the previous single check solution
- prevents future instances from happening

Footer

One or more footers can be provided one blank line after the body. The footer can be indicated by either a :<space> or <space># separator, followed by a string value. Breaking changes can be communicated here as, BREAKING CHANGE: This is important.. Reviews can be indicated here as, Design-reviewed-by: Designer Name. Jira tickets on closing commits need to be indicated as, #VDS-2095.

fix(radio): removes the double check issue

- undoes the previous single check solution
- prevents future instances from happening

BREAKING CHANGE: This is important.
Authored-by: Thirumalaa Srinivas
Accessibility-reviewed-by: Erik Thomas
#VDS-2095

Breaking changes

The best way so far, seems to be with using the phrase in the footer as shown below.

The <type>[optional scope]!: <description> method seems to throw errors on commitlint. Relevant rule added subject-exclamation-mark do not seeem to make an impact, yet.

fix(readme): retries convention details in dev commit docs

BREAKING CHANGE: retries this
#VDS-2095

Ticket number

It's best to add the ticket (Jira ticket or Github issue) number during the final commit of the bug fix or feature. The below examples use Jira tickets.

fix(readme): updates section in dev commit docs

#VDS-2095

It shows up as closing the ticket in the change log.

# 4.2.0 (2021-08-09)

## Features

- readme: updates section in dev commit docs (78ec2cd), closes #VDS-2095

For frequent code committers.

The below practice ensures a crisp CHANGELOG.md for the developer community to grok.

For UI users in IDE or Code Editors.

This could be one of, but not limited to, SourceTree, VSCode, WebStorm, SublimeText, Atom, IntelliJ.

docs(readme): updates documentation

#VDS-100

For git CLI users.

git commit -m "docs(readme): updates documentation" -m "#VDS-100"

Build Process

Stage Steps
1 Install Packages
2 Prebuild Lib
3 Build Lib
4 Prebuild Docs
5 Test, Postbuild
6 Build Docs
7 (Only on main) Build Docs (Versioned)
8 Deploy UI, Deploy Package

Closing

Remember that your commit messages are going to be used in creating the CHANGELOG.md file. So, please use thoughtful commit messages.

When in doubt, keep PR's small. To give a PR the best chance of getting accepted, don't bundle more than one feature or bug fix per pull request. It's always best to create two smaller PRs than one big one.

When adding new features or modifying existing, please include tests to confirm the new behavior.