Skip to content
This repository has been archived by the owner on Jan 30, 2024. It is now read-only.

Latest commit

 

History

History
202 lines (141 loc) · 13.7 KB

CONTRIBUTING.md

File metadata and controls

202 lines (141 loc) · 13.7 KB
Raw

Welcome

We're so glad you're thinking about contributing to a U.S. Government open source project! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions.

How to contribute to this project

  • We want to ensure a welcoming environment for all of our projects. Our staff follows this Code of Conduct and all contributors should do the same.
  • Report bugs and request features via Github Issues
  • Create a Github pull request with new functionality or fixing a bug.
  • Improve or create documentation.
  • Help us improve our tests.
  • Triage tickets and review patches triaging-tickets created by other users.

Public domain

As noted in LICENSE, this project is in the worldwide public domain (in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication).

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

Issue Guidelines

In the interest of making it easier for our contributors to manage site issues, we request that issues follow certain guidelines. Our developers mainly use issues to identify and prioritize their work. If you have questions about the theme or would like start a general discussion, we kindly request that you email us at gsalabs@gsa.gov. Our issue guidelines are a living document and a work in progress, so feel free to offer feedback on it, by emailing us at gsalabs@gsa.gov

  • Specific: The issue makes specific requests. An example of a specific request would be Reduce the Size of Images. An example of a non-specific request would be Improve Site Performance.
  • Measurable: The issue has specific requirements and can be closed when those requirements are met. This helps us track the progress in addressing problems. For example, tech debt is always something to work on, so we should create separate issues for this, such as Consolidate Styling of Repo and Task Cards and Convert Validator from Monaco Editor to jsoneditor, rather than Address Tech Debt.
  • Actionable: An issue should request a specific action from a member of the code.gov team or community. An example of something actionable would be Remove Debugging Text from Loading Screen. An example of something that isn't actionable by our team or community is My city should be forking Code.gov.
  • Realistic: The issue is something that is achievable by the resources of the project, including contributions from the open source community. An example of a realistic issue is Include Line Numbers in Validator.
  • Time-Aware: The issue is something that can be resolved within 6 months. If you think your issue might take longer, we encourage you to break up your issues into smaller issues (like stepping stones) that we can address. We can still work on big problems, but it is easier for us to track progress and identify what we need to work on, when big problems are broken up into smaller ones.

Code Guidelines

When creating a new feature, one should think about the broad variety of uses for a given component and design it in such a way that the end user can adjust via Experience Builder as needed. Fields expecting long text strings tend to result in a poor builder experience as they cannot view all of the content at once in the editing pane. For that reason, this theme has opted away from such experiences.

If making changes to the theme itself, uswdsTheme, provide the ability to toggle a component on/off or have it collapse down to zero height if not in use.

We use Prettier as the default formatter for our code. This ensures a consistent product across all files an enhances readability. More information about Prettier can be found at https://prettier.io/.

Establishing a Development Environment

Using Salesforce Scratch Orgs is the easiest way to get up and running with the repository. See INSTALLATION for specific instructions to deploy this code base to a fresh environment with SFDX.

Creating a new Component

sfdx force:lightning:component:create -d src/aura -n {component name}

Add the new component to the src/package.xml

sfdx force:source:manifest:create --sourcepath src --manifestname src/package.xml

Handling in-component validation & builder feedback

The builderNotification component provides a means by which validation messages and feedback for developers or site builders can be shared within Experience Builder. Messages that appear in Experience Builder are meant to serve as bowling lane bumpers to steer the individual back on track. If a site builder publishes a page while a message is displayed, it will be shown to end users.

Implementing builderNotification relies on updates to the component and controller or helper. The standard practice is to give the component an aura:id of builderNotification but that naming convention is not explicitly required.

The addNotification method expects an object or array of objects containing a title and message. A simplified example is below. For a more detailed example see the Step Indicator component.

<!-- mycomponent.cmp -->
<aura:attribute name="firstName" type="String" />
<!-- component must be implemented with an aura:id="builderNotification" -->
<c:builderNotification aura:id="builderNotification" />
<h1>Hi {!v.firstName}</h1>
/* mycomponentController.js */
validateFirstName: function(component, event, helper) {
  if ({!v.firstName}) {
    const builderNotificationContent = [{
        title: "Error - My Component",
        message: "First name is blank and a value is expected"
      }];
    component.find("builderNotification").addNotification(builderNotificationContent);
  }
}

Accessibility

The US Web Design System and Salesforce Lightning Design System have been built with acessibility in mind. Overviews of their policies can be found at USWDS Accessibility ahd Lightning Design System Accessibility

This theme aims to build upon the foundation provided by the USWDS and SLDS to provide a set of accessible components. Automated accessibility tests as well as validations should be incorporated into the workflow of any updates.

Testing Accessibility

New or updated components should be tested using the Web Content Accessibility Guidelines (WCAG) 2 Level AA standard. The easiest way to test components in an automated fashion is to use the Google Lighthouse NPM package and point at a published community page containing just the component. Similarly, one can run Lighthouse from within the Chrome browser and select the accessibility checkbox For example:

npx lighthouse https://inspiration-ability-2765.scratch.my.site.com/issue111/s/ --only-categories=accessibility --view --output html

The resulting HTML file will contain details about any accessibility issues present in the component. When in doubt, it is best to consult a resource trained in web accessibility.

Validation

Whenever images are utilized in a component, alt text should be an editable attribute. Validating that alt text is not blank and providing a Builder Notification warning to the user is preferred. For example, the USWDS Hero component will issue this warning to users if alt text is blank, "Alt Text is missing for the background image. Here is more info about how to write great alt text, https://www.w3.org/TR/WCAG20-TECHS/H37.html." This is not foolproof but attempts to steer the user back on track.

Testing

Lightning Testing Service is used to run automated Jasmine tests against each component. Tests are captured in the test/staticresources directory and named using the following pattern, uswds_lts_{component name}.

Testing Principles

Tests should follow the Arrange, Act, Assert principle. Test describe and it statements should read as sentences so as to be readily consumed by a developer or site manager. Muliple assertions may be present in a given test. For example, the following contains two assertions (expect()) within a single test so as to verify all relevant text is present.

describe("USA Banner", function () {
  it("Displays default banner text", function (done) {
    $T.createComponent("c:uswdsUSABanner", {}, true).then(function (component) {
      expect(
        document.getElementsByClassName("usa-banner__header-text")[0]
          .textContent
      ).toContain("An official website of the United States government");
      expect(
        document.getElementsByClassName("usa-banner__header-action")[0]
          .textContent
      ).toContain("Here’s how you know");
    });
  });
});

Creating New Tests

  1. Tests are stored in staticResources, create a new file,

    sfdx force:lightning:test:create -d test/staticresources -n uswds_lts_{component name}

  2. The prior command creates a bare test.

    1. If you are using VSCode, tests can be quickly scaffolded using snippets. Open the new file and start typing LtngTest, pick the describe option.
    2. If not using VSCode, copy in the contents of test/testTemplate.

    cp test/testTemplate test/staticresources/uswds_lts_{component name}.resource

  3. Once the test has been created, it should be referenced in test/aura/jasmineTests/jasmineTests.app.

  4. Add the new staticresource to package.xml. This command also supports the removal of files.

    sfdx force:source:manifest:create --sourcepath test --manifestname test/package.xml

Deploying Tests

sfdx force:mdapi:deploy -d test/ -w 50 -u {username}

Running Tests

Tests can be run via the CLI or directly within the browser. Per issue #108, a fork of Salesforce's Lightning Test Service Plugin was created.

CLI

  • Install forked version of Salesforces Lightning Test Service plugin
  • sfdx plugins:install @mvogelgesang/plugin-lightning-testing-service
  • Verify installation via sfdx plugins
  • Deploy source and test to org following steps above
  • Run tests sfdx aura-test:run -a jasmineTests -u {username}
  • A browser window will launch and test results will be printed to the terminal

Browser

  • Deploy tests and navigate straight to the test suite:
  • sfdx force:org:open -p /c/jasmineTests.app -u {username}
Known Issues
  • As of Salesforce v57.0 (Spring '23), Salesforce introduced Lightning Web Security for Lightning web components (GA) and Aura components (Beta) which is enabled by default on new and scratch orgs. Enabling this feature causes the Jasmine test suite to error out by not recognizing the global $T variable. To turn this off, go to Setup > Session Settings > Lightning Web Security and uncheck Use Lightning Web Security for Lightning web components (GA) and Aura components (Beta). Since turning this off is only to execute tests, suggest toggling off the setting, validating tests, and turning it back on.

Updating package.xml version number

  • Deploy code from src/ as is to fresh org
  • Update package.xml to desired mdapi version within src/
  • Pull the code that was just deployed back down to your local machine but using the new mdapi version
  • sfdx force:mdapi:retrieve -r newmdapi/ -k src/package.xml --unzip -u {username}
  • copy contents of newmdapi/ and paste into src/.
  • Run prettier against files to resolve whitespace differences caused by mdapi:retrieve.
  • npx prettier --write "src/"
  • Review remaining files that are in a git dirty state. flexipage and communityThemeDefinition files may change structure since they are xml-based.
  • deploy updated metadata back to org sfdx force:mdapi:deploy -d src/ -w 100 -u {username}
  • deploy tests to org sfdx force:mdapi:deploy -d test/ -w 100 -u {username}
  • run tests sfdx aura-test:run -a jasmineTests -u {username}
  • upon successful test run, perform same metadata api update as above but for the test/ directory
  • deploy and run tests again