NGX-PFE - Page Flow Engine

Contributing to NGX-PFE

We would love for you to contribute to the PFE codebase! As a contributor, here are the guidelines we would like you to follow:

1. Got a Question?

Please look at the list of open/closed issues and discussions. If you didn't find an answer to your question, please open a GitHub discussion.

2. Found a Bug?

If you find a bug in PFE or a mistake in the documentation, you can help us by submitting a bug report to our GitHub Repository. Even better, you can submit a Pull Request with a fix.

3. Missing a Feature?

You can request a new feature by submitting a feature request to our GitHub Repository.

We appreciate very much if you are willing to implement the feature. In that case, please wait for us to discuss your feature request and accept it. This process allows us to better coordinate our efforts, keep a healthy codebase and a meaningful set of features, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.

4. Project Structure

Source code and documentation are included in the top-level folders listed below:

  • additional-documentation - Markdown and asset files for documentation
  • apps - ngx-pfe-viewer application, which is a live example of the ngx-pfe library
  • ci - CI/CD pipelines
  • libs - Source code for the ngx-pfe library
  • scripts - Miscellaneous scripts for project tasks such as building documentation, generating schemas or publishing.

5. Most relevant commands

  • Install workspace dependencies: npm install
  • Build the PFE library: npm run build:lib
  • Run the tests in the PFE library: npm run test
  • Start the pfe-viewer application locally: npm start
  • Start the docs application locally: npm run docs:watch

6. Submission Guidelines

Before doing any submission, please search the issue tracker and the discussions. An issue or discussion for your problem may already exist and has been resolved, or a comment in them might inform you of workarounds readily available.

6.1. Submitting a Bug Report

We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. Having a reproducible scenario gives us a wealth of important information without going back and forth with you requiring additional information. A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem.

We will be insisting on a minimal reproduction in order to save maintainers' time and ultimately be able to fix more bugs. Interestingly, from our experience, users often find coding problems themselves while preparing a minimal reproduction repository. We understand that sometimes it might be hard to extract essentials bits of code from a larger codebase, but we really need to isolate the problem before we can fix it.

You can file a new bug report by filling out the corresponding template in our issue form.

6.2. Submitting a Feature Request

When proposing a new feature, please make sure you are making your point very clear. We need to understand the use case, the problem it solves, and the general approach you have in mind to solve it.

To file a feature request, please fill out the dedicated template in our issue form.

6.3. Submitting a PR

Before submitting a PR please make sure your code changes are ready to be reviewed by checking the following:

When submitting a PR (here), please make sure to fill out the template completely. The template is there to help you and to make sure you don't forget anything.

After a PR is merged to the main branch, a new beta version will be automatically released. You can use that version to try out your changes in your own project. To find out the version number, you can run either this command: npm info @allianz/ngx-pfe@next version, or check if there is a release commit after your PR merge commit in the main branch in the ngx-pfe repo: git log -n 2 --oneline

If your PR provides a Breaking Change, do the following:

  • Add ! after the type in the PR title to indicate that the PR contains breaking changes (e.g., feat!: breaking change feature)
  • Provide a proposal for the Breaking Change message in the PR description, so that it can also be reviewed. This message will be used in the release notes.
  • If you are the one eventually merging the PR, make sure to add the Breaking Change message to the merge commit, via the GitHub UI. For example:
    feat!: breaking change feature

BREAKING CHANGE: Here the message with markdown formatting

You can find the official docs about this topic in the conventional commits docs (here)

6.4. Commit Message Guidelines

  • We enforce conventional commits with @commitlint/config-conventional

  • Scopes are not in use yet. You can skip them. Commit messages will therefore look like

    feat: provide a new service to monitor scrolling

fix: downgrade rxjs to prevent an error with the current Angular version

  • Don't forget to provide more information about the commit in the body of the message, if needed.

  • Ensure to mark Breaking Changes with the appropriate notice in the commit footer.

results matching ""

    No results matching ""