Byrd Angular Modules

This project was generated with Angular CLI version 6.2.1.

It contains the shared byrd packages for angular apps. See the README.md files within the individual projects for more.

Playground

The main project within this repo, located within the src folder, is a playground which can be used to practically test the packages. To use:

1. Ensure that all packages are built using ./bin/build-all
2. Run npm run start and open up your browser to localhost:4200
3. Modify the app.component.ts file as necessary, the server will automatically rebuild

Package Structure

• Packages are created using npm run ng -- generate library <name>. This uses the Angular CLI and ng-packagr to create a new library within the projects folder.
• Within the package, modify the package.json as necessary. In particular:
  • The name will need to be changed to be scoped relative to the @getbyrd/ namespace
  • The package license should be given as UNLICENSED
  • The peer dependencies should be updated
• You will then need to update the paths reference within the global tsconfig.json file
• In line with Angular's project structure, each package should have its tests outside of the project, within a test directory. This allows the tests to use multiple packages (particularly important, it allows them to use the @getbyrd/testing package). You will need to also update the context defined within the src/test.ts file to point to this folder.

Contributing

Debugging

Bad Definition Files

• One common issue found when using ng-packagr is that it incorrectly generates the definition files, making relative import() statements (e.g. ../../dist/core), rather than absolute (e.g. @getbyrd/core) when referring to interfaces across projects. As an example:

  // Automatically generated returns.selectors.d.ts
  declare const selectReturnsStatus: import("@ngrx/store").MemoizedSelector<object, import("../../../../dist/core/lib/ngrx/core.state").LoadingStatus>;

  In such situations, this can be fixed by explicitly referring to the types:

  // Updated returns.selectors.ts with explicit typing
  import { LoadingStatus } from '@getbyrd/core';
  
  const selectReturnsStatus = createSelector(
    selectReturnState, state => (state.status as LoadingStatus),
  );

Package Versioning

• Package versions follows the Angular approach, in which all packages are bumped in one go, such that all packages have the same version number. This allows package users to install only the packages they need, whilst simplifying compatibility issues.

Automated Workflow

1. Whenever you make a change, update the CHANGELOG.md for the specific package - adding or extending the "unreleased" section as necessary. All updates should conform to the Keep a changelog standards. For example:

   [Unreleased]
   ## Fixed
   * Stack overflow error

2. Once finished with your feature, create a pull-request, and merge your changes into the develop branch
3. Repeat the process as necessary
4. When you're ready to create a new version of the @getbyrd packages, find the "Byrd_Ng_Packages_Publisher" project within Jenkins, and hit the "Build Now" button. This runs the bump-and-publish script, which:
   • Creates a new build branch from develop
   • Automatically calculates the next version for the packages, based on the contents of the CHANGELOG.md files (hence, why they are so important)
   • Updates all of the CHANGELOG.md and package.json files to reflect the new version
   • Commits, and pushes the changes to the develop branch
   • Creates a tag with the version number, e.g. x.y.z
   • Merges develop into master
   • Builds all of the projects, and publishes them all to NPM

Manual Publishing

If manual publishing of a package is necessary, use the bump-and-publish script as an up-to-date guide of the process to be followed. Always be sure to:

1. Lint the packages npm run lint:all
2. Test the packages npm run test:all
3. Bump the package versions npm run bump
4. Commit the changes, create a PR, squash into develop
5. Build the packages with their new versions npm run build:all
6. Publish each package in turn
   • Move to its build directory dist/<package>
   • Publish the app npm publish
   • note: You will need to first login to NPM in order to do this (credentials in 1Password).
7. Merge into master

Release-Candidates

During development, you'll often want to be able to practically test your work against one of the dashboard. To do this you can simply build a single project, and install it locally (for which, you'll need to npm link, and preserve symlinks), however this can be a cumbersome process to set-up and teardown. Instead, you may wish to simply publish a release candidate version to NPM, and then install it within the project you're testing.

To create a release candidate:

1. Update the package.json of the project(s) you're wishing to test
   • Calculate the next package version. For this you can:
     • Use ./bin/version-bump --next to get the next version, OR
     • Use npm view @getbyrd/<package> version to get the latest published version, and calculate yourself the next version from this
2. Set the version to <major>.<minor>.<patch>-rc.<candidate> as necessary (e.g. 1.0.25-rc.1)
3. Run the ./bin/build-and-test -p <packages> script with the relevant package names
4. Go to the dist/<package> folder, and run npm publish
   • For this you will need an NPM publishable API key - ask a team member for help if necessary

Helpful Aliases

You may find the following bash aliases helpful:

# Change to the ng-byrd repo and activate nvm
alias cdng='cd <REPO_HOME>; nvm use'

# Run the `ng` binary from within the `node_modules`
# e.g. $ nng build inventory
alias nng='npm run ng -- '

# Show the latest version of the given @getbyrd package
# e.g. $ nglatest federkleid
function nglatest () {
  npm view @getbyrd/$1 version
}