Skip to content

Latest commit

 

History

History
90 lines (58 loc) · 6.63 KB

CONTRIBUTING.md

File metadata and controls

90 lines (58 loc) · 6.63 KB
Raw

Contribution Guide

This section aims to familiarise developers to the Polkadot Staking Dashboard [GitHub, Demo] for the purpose of contributing to the project.

Reach out to ross@parity.io for clarification of any content within this document.

Submitting Pull Requests

This project follows the Conventional Commits specification. Pull requests are merged and squashed, with the pull request title being used as the commit message. Commit messages should adhere to the following structure:

<type>(<scope>): <summary>

Some example PR titles:

  • feat: implement help overlay
  • feat(auth): implement login API
  • fix(button): resolve issue with button alignment
  • docs(readme): add installation section
  • chore(tests): refactor user tests

The (scope) could be anything specifying the place of the commit change. For example, api, app, cli, etc.

If you would like to know more about the Conventional Commits specification, please visit the Conventional Commits website.

Releases

Release Please is used for automating staking dashboard's changelog and release generation.

Release Please is a GitHub action maintained by Google that automates CHANGELOG generation, the creation of GitHub releases, and version bumps. [Gtihub docs, Action]

Major Packages Used

  • React 18
  • Polkadot JS API [docs]
  • React Chart JS 2 for graphing. [docs, React docs]
  • Framer Motion. [docs]
  • Font Awesome for the majority of icons. Ionicons for side menu footer icons
  • SCSS for theme configuration and Styled Components [docs] for component styling.

Environment Variables

Optionally apply envrionment variables in an environment file such as .env or with yarn build to customise the build of staking dashboard.

Refer to the .env file in the root of the repository for all supported variables.

Config Files

There are some ad-hoc files defining app configuration where needed. These just provide a means of bootstrapping app data, and further abstraction could be explored in the future.

  • config/pages.ts: provides the pages and page categories of the app.
  • config/help.ts: provides the help content.
  • Utils.ts: Various general helper functions used throughout the app, such as formatting utilities.

Folders

Folders are structured in the src/ directory to separate functional, presentational and context components:

  • contexts: context providers for the app. All Polkadot JS API interaction happens in these files.
  • img: app SVGs.
  • library: reusable components that could eventually be abstracted into a separate UI library.
  • modals: the various modal pop-ups used in the app.
  • pages: similar to modals, page components and components that comprise pages.
  • workers: web workers that crunch process-heavy scripts. Only one exists right now, that iterates erasStakers and calculates active nominators and minimum nomination bond.

App Entry

Going from the top-most component, the component hierarchy is set up as follows:

  • index.tsx: DOM render, of little interest.
  • App.tsx: wraps <App /> in the theme provider context and determines the active network from local storage.
  • Providers.tsx: imports and wraps <Router /> with all the contexts using a withProviders hook. We also wrap styled component's theme provider context here to make the theme configuration work.
  • Router.tsx: contains react router <Route>'s, in addition to the major app presentational components.

Development Patterns

Documenting some of the development patterns used:

  • We use the "Wrapper" terminology for styled components that wrap a functional component.
  • Styles are defined on a per-component basis, being defined in the same folder as the component markup itself. Where unavoidable (such as global styles, interface layout), styled components should reside in src/Wrappers.ts.
  • Theme values are configured in styles/theme.scss, and can be included in any styled component as custom properties. Graph colors are configurable from styles/graphs.ts.
  • Constants or default values (such as those waiting for Polkadot API) are defined in src/constants.ts.
  • Packages with missing TypeScript definitions can be declared in src/react-app-env.d.ts.

TypeScript Support

The majority of components have types. Type additions are welcome for data that makes sense to type (e.g. data that is unlikely to change as we continue development).

Strict mode is used in development, so types are always required for objects.