Skip to content

Latest commit

 

History

History
309 lines (223 loc) · 14.8 KB

CONTRIBUTING.md

File metadata and controls

309 lines (223 loc) · 14.8 KB
Raw

SCION Microfrontend Platform

SCION Microfrontend Platform Projects Overview Changelog Contributing Sponsoring

Contributing

We encourage other developers to join the project and contribute to making SCION products constantly better and more stable. If you are missing a feature, please create a feature request so we can discuss it and coordinate further development. To report a bug, please check existing issues first, and if found, leave a comment on the issue. Otherwise, file a bug or create a pull request with a proposed fix.

Submitting a Pull Request

This section explains how to submit a pull request.

  1. Login to your GitHub account and fork the SchweizerischeBundesbahnen/scion-microfrontend-platform repo.
  2. Make your changes in a new Git branch. Name your branch in the form issue/123 with 123 as the related GitHub issue number. Before submitting the pull request, please make sure that you comply with our coding and commit guidelines.
  3. Run the command npm run before-push to make sure that the project builds, passes all tests, and has no lint violations. Alternatively, you can also run the commands one by one, as following:
    • npm run lint
      Lints all project files.
    • npm run build
      Builds the project and related artifacts.
    • npm run test:headless
      Runs all unit tests.
    • npm run e2e:headless
      Runs all end-to-end tests.
  4. Commit your changes using a descriptive commit message that follows our commit guidelines.
  5. Before submitting the pull request, ensure to have rebased your branch based on the master branch as we stick to the rebase policy to keep the repository history linear.
  6. Push your branch to your fork on GitHub. In GitHub, send a pull request to scion-microfrontend-platform:master.
  7. If we suggest changes, please amend your commit and force push it to your GitHub repository.

When we receive a pull request, we will carefully review it and suggest changes if necessary. This may require triage and several iterations. Therefore, we kindly ask you to discuss proposed changes with us in advance via the GitHub issue.

Development

Make sure to use Node.js version 20.14.0 for contributing to SCION. We suggest using Node Version Manager if you need different Node.js versions for other projects.

For development, you can uncomment the section PATH-OVERRIDE-FOR-DEVELOPMENT in tsconfig.json. This allows running tests or serving applications without having to build dependent modules first.

The following is a summary of commands useful for development of scion-microfrontend-platform. See file package.json for a complete list of available NPM scripts.

Commands for working on the microfrontend-platform library

  • npm run microfrontend-platform:lint
    Lints the microfrontend-platform library.

  • npm run microfrontend-platform:build
    Builds the microfrontend-platform library.

  • npm run microfrontend-platform:test
    Runs unit tests of the microfrontend-platform library.

  • npm run microfrontend-platform:analyze
    Displays the content of the library if installed in a client app. Use to verify the library to be tree shaken correctly, i.e., that the host module is not included.

Commands for running end-to-end tests

  • npm run e2e:run
    Runs end-to-end tests of the microfrontend platform. Prior to test execution, starts four instances of the microfrontend-platform-testing-app.

  • npm run e2e:debug
    Runs end-to-end tests of the microfrontend platform in debug mode. Prior to test execution, starts four instances of the microfrontend-platform-testing-app.

  • npm run e2e:lint
    Lints end-to-end tests.

Commands for working on the testing application and devtools

  • npm run start
    Serves four instances of the microfrontend-platform-testing-app and the microfrontend-platform-devtools. Open the page http://localhost:4201 to load the microfrontend platform testing app into your browser.
    Uncomment the section PATH-OVERRIDE-FOR-DEVELOPMENT in tsconfig.json to have hot module reloading support.

  • npm run microfrontend-platform-testing-app:lint
    Lints the microfrontend-platform-testing-app.

  • npm run microfrontend-platform-devtools:lint
    Lints the microfrontend-platform-devtools.

Commands for generating the project documentation

  • npm run microfrontend-platform:adoc
    Use to build the Developer Guide, i.e., creates a HTML file from the AsciiDoc source files. The output is written to dist/microfrontend-platform-developer-guide.

  • npm run microfrontend-platform:typedoc
    Use to generate the TypeDoc for the SCION Microfrontend Platform library. The output is written to dist/microfrontend-platform-api.

  • npm run changelog
    Use to generate the changelog based on the commit history. The output is written to CHANGELOG.md, which will be included in docs/site/changelog/changelog.md using the template docs/site/changelog/changelog.template.md.

Code Formatting

To ensure consistency within our code base, please use the following formatting settings.

  • For IntelliJ IDEA
    Import the code style settings of .editorconfig.intellij.xml located in the project root.

  • For other IDEs
    Import the code style settings of .editorconfig located in the project root.

Coding Guidelines

In additional to the linting rules, we have the following conventions:

  • We believe in the Best practices for a clean and performant Angular application and the Angular Style Guide.
  • We expect line endings to be Unix style (LF) only. Please check your Git settings to not convert line endings to CRLF. You can run the following command to find files with windows-style line endings: find . -type f | xargs file | grep CRLF.
  • Observable names are suffixed with the dollar sign ($) to indicate that it is an Observable which we must subscribe to and unsubscribe from.
  • We use explicit public and private visibility modifiers (except for constructors) to make the code more explicit.
  • We prefix private members with an underscore.
  • We write each RxJS operator on a separate line, except when piping a single RxJS operator. Then, we write it on the same line as the pipe method.
  • We avoid nested RxJS subscriptions.
  • We document all public API methods, constants, functions, classes or interfaces.
  • We structure the CSS selectors in CSS files similar to the structure of the companion HTML file and favor the direct descendant selector (>) over the non-restrictive descendant selector ( ), except if there are good reasons not to do it. This gives us a visual by only reading the CSS file.
  • When referencing CSS classes from within E2E tests, we always prefix them with e2e-. We never reference e2e prefixed CSS classes in stylesheets.
Commit Guidelines

We believe in a compact and well written Git commit history. Every commit should be a logically separated changeset. We use the commit messages to generate the changelog.

Each commit message consists of a header, a summary and a footer. The header has a special format that includes a type, an optional scope, and a subject, as following:

<type>(<scope>): <subject>

[optional summary]

[optional footer]
Type
  • feat: new feature
  • fix: bug fix
  • docs: changes to the documentation
  • refactor: changes that neither fixes a bug nor adds a feature
  • perf: changes that improve performance
  • test: adding missing tests, refactoring tests; no production code change
  • chore: other changes like formatting, updating the license, removal of deprecations, etc
  • deps: changes related to updating dependencies
  • ci: changes to our CI configuration files and scripts
  • revert: revert of a previous commit
  • release: publish a new release
Scope

The scope should be the name of the NPM package or application affected by the change.

The following scopes are allowed:

  • platform: If the change affects the @scion/microfrontend-platform NPM package.
  • devtools: If the change affects the SCION DevTools application.
  • testapp: If the change only affects the internal test application.
Subject

The subject contains a succinct description of the change and follows the following rules:

  • written in the imperative, present tense ("change" not "changed" nor "changes")
  • starts with a lowercase letter
  • has no punctuation at the end
Summary

The summary describes the change. You can include the motivation for the change and contrast this with previous behavior.

Footer

In the footer, reference the GitHub issue and optionally close it with the Closes keyword, as following:

closes #123

And finally, add notes about breaking changes, if there are any. Breaking changes start with the keyword BREAKING CHANGE: . The rest of the commit message is then used to describe the breaking change and should contain information about the migration.

BREAKING CHANGE: Removed deprecated API for xy.

To migrate:
- do xy
- do xy
Deprecation Policy

You can deprecate an API in any version. Deprecated APIs are only removed in a major release.

When deprecating API, mark it with the @deprecated JSDoc comment tag and include the current library version. Optionally, you can also specify which API to use instead, as following:

/**
 * @deprecated since version 2.0. Use {@link otherMethod} instead.
 */
function someMethod(): void {
}
Deployments

We deploy our documentations and applications to Vercel. Vercel is a cloud platform for static sites and serverless functions. Applications are deployed using the SCION collaborator account ([email protected]) under the SCION organization.

We have the following microfrontend-platform related projects:

NPM Packages

We publish our packages to the NPM registry. Packages are published using the SCION collaborator account (scion.collaborator) under the SCION organization.

We have the following microfrontend-platform related packages:

Versioning

SCION Microfrontend Platform follows the semantic versioning scheme (SemVer) for its releases. For more information, see our version policy.

Release Checklist

This chapter describes the tasks to publish a new release to NPM.

  1. Update the following package.json files with the new version:
    • /package.json
    • /projects/scion/microfrontend-platform/package.json
    • ensure version constant in projects/scion/microfrontend-platform/src/lib/microfrontend-platform.ts to be the same version as in /projects/scion/microfrontend-platform/package.json.
  2. Run npm install to update the version in package-lock.json.
  3. Run npm run changelog to generate the changelog. Then, review the generated changelog carefully and correct typos and formatting errors, if any.
  4. Commit the changed files using the following commit message: release: vX.X.X. Replace X.X.X with the current version. Later, when merging the branch into the master branch, a commit message of this format triggers the release action in our GitHub Actions workflow.
  5. Push the commit to the branch release/X.X.X and submit a pull request to the master branch. Replace X.X.X with the current version.
  6. When merged into the master branch, the release action in our GitHub Actions workflow does the following:
  7. Migrate the Getting Started Guide Git Repo if necessary.