awx/CONTRIBUTING.md

Ansible AWX/Tower V2

Hi there! We're excited to have you as a contributor.

Have questions about this document or anything not covered here? Feel free to reach out to any of the contributors of this repository found here: https://github.com/ansible/awx-pf/graphs/contributors

Table of contents

• Things to know prior to submitting code
• Setting up your development environment
  • Prerequisites
    • Node and npm
• Build the user interface
• Accessing the AWX web interface
• Working with React
  • App structure
  • Naming files
  • Class constructors vs Class properties
  • Binding
  • Typechecking with PropTypes
  • Naming Functions
  • Default State Initialization

Things to know prior to submitting code

• All code submissions are done through pull requests against the master branch.
• If collaborating with someone else on the same branch, please use --force-with-lease instead of --force when pushing up code. This will prevent you from accidentally overwriting commits pushed by someone else. For more information, see https://git-scm.com/docs/git-push#git-push---force-with-leaseltrefnamegt

Setting up your development environment

The UI is built using ReactJS and Patternfly.

Prerequisites

Node and npm

The AWX UI requires the following:

• Node 8.x LTS
• NPM 6.x LTS

Run the following to install all the dependencies:

(host) $ npm run install

Build the User Interface

Run the following to build the AWX UI:

(host) $ npm run start

Accessing the AWX web interface

You can now log into the AWX web interface at https://127.0.0.1:3001.

Working with React

App structure

All source code lives in the /src directory and all tests live in the /__tests__ directory (mimicing the internal structure of /src).

Inside these folders, the internal structure is:

• /components - All generic components that are meant to be used in multiple contexts throughout awx. Things like buttons, tabs go here.
• /contexts - Components which utilize react's context api.
• /pages - Based on the various routes of awx.
  • /components - Components that are meant to be used specifically by a particular route, but might be sharable across pages of that route. For example, a form component which is used on both add and edit screens.
  • /screens - Individual pages of the route, such as add, edit, list, related lists, etc.
• /util - Stateless helper functions that aren't tied to react.

Bootstrapping the application (root src/ files)

In the root of /src, there are a few files which are used to initialize the react app. These are

• index.jsx
  • Connects react app to root dom node.
  • Sets up root route structure, navigation grouping and login modal
  • Calls base context providers
  • Imports .scss styles.
• app.jsx
  • Sets standard page layout, about modal, and root dialog modal.
• RootProvider.jsx
  • Sets up all context providers.
  • Initializes i18n and router

Naming files

Ideally, files should be named the same as the component they export, and tests with .test appended. In other words, <FooBar> would be defined in FooBar.jsx, and its tests would be defined in FooBar.test.jsx.

Naming components that use the context api

File naming - Since contexts export both consumer and provider (and potentially in withContext function form), the file can be simplified to be named after the consumer export. In other words, the file containing the Network context components would be named Network.jsx.

Component naming and conventions - In order to provide a consistent interface with react-router and lingui, as well as make their usage easier and less verbose, context components follow these conventions:

• Providers are wrapped in a component in the FooProvider format.
  • The value prop of the provider should be pulled from state. This is recommended by the react docs, here.
  • The provider should also be able to accept its value by prop for testing.
  • Any sort of code related to grabbing data to put on the context should be done in this component.
• Consumers are wrapped in a component in the Foo format.
• If it makes sense, consumers can be exported as a function in the withFoo() format. If a component is wrapped in this function, its context values are available on the component as props.

Class constructors vs Class properties

It is good practice to use constructor-bound instance methods rather than methods as class properties. Methods as arrow functions provide lexical scope and are bound to the Component class instance instead of the class itself. This makes it so we cannot easily test a Component's methods without invoking an instance of the Component and calling the method directly within our tests.

BAD:

  class MyComponent extends React.Component {
    constructor(props) {
      super(props);
    }

    myEventHandler = () => {
      // do a thing
    }
  }

GOOD:

  class MyComponent extends React.Component {
    constructor(props) {
      super(props);
      this.myEventHandler = this.myEventHandler.bind(this);
    }

    myEventHandler() {
      // do a thing
    }
  }

Binding

It is good practice to bind our class methods within our class constructor method for the following reasons:

1. Avoid defining the method every time render() is called.
2. Performance advantages.
3. Ease of testing.

Typechecking with PropTypes

Shared components should have their prop values typechecked. This will help catch bugs when components get refactored/renamed.

About.propTypes = {
  ansible_version: PropTypes.string,
  isOpen: PropTypes.bool,
  onClose: PropTypes.func.isRequired,
  version: PropTypes.string,
};

About.defaultProps = {
  ansible_version: null,
  isOpen: false,
  version: null,
};

Naming Functions

Here are the guidelines for how to name functions.

Naming Convention	Description
handle<x>	Use for methods that process events
on<x>	Use for component prop names
toggle<x>	Use for methods that flip one value to the opposite value
show<x>	Use for methods that always set a value to show or add an element
hide<x>	Use for methods that always set a value to hide or remove an element
create<x>	Use for methods that make API POST requests
read<x>	Use for methods that make API GET requests
update<x>	Use for methods that make API PATCH requests
destroy<x>	Use for methods that make API DESTROY requests
replace<x>	Use for methods that make API PUT requests
disassociate<x>	Use for methods that pass { disassociate: true } as a data param to an endpoint
associate<x>	Use for methods that pass a resource id as a data param to an endpoint

Default State Initialization

When declaring empty initial states, prefer the following instead of leaving them undefined:

this.state = {
  somethingA: null,
  somethingB: [],
  somethingC: 0,
  somethingD: {},
  somethingE: '',
}

Testing components that use contexts

We have several React contexts that wrap much of the app, including those from react-router, lingui, and some of our own. When testing a component that depends on one or more of these, you can use the mountWithContexts() helper function found in __tests__/enzymeHelpers.jsx. This can be used just like Enzyme's mount() function, except it will wrap the component tree with the necessary context providers and basic stub data.

If you want to stub the value of a context, or assert actions taken on it, you can customize a contexts value by passing a second parameter to mountWithContexts. For example, this provides a custom value for the Network context:

const network = {
  api: {
    getOrganizationInstanceGroups: jest.fn(),
  }
};
mountWithContexts(<OrganizationForm />, {
  context: { network },
});

In this test, when the OrganizationForm calls api.getOrganizationInstanceGroups from the network context, it will invoke the provided stub. You can assert that this stub is invoked when you expect or to provide stubbed data.

The object containing context values looks for five known contexts, identified by the keys linguiPublisher, router, config, network, and dialog — the latter three each referring to the contexts defined in src/contexts. You can pass false for any of these values, and the corresponding context will be omitted from your test. For example, this will mount your component without the dialog context:

mountWithContexts(<Organization />< {
  context: {
    dialog: false,
  }
});