Development Guidelines - hslayers/hslayers-ng GitHub Wiki

Component and naming style guide

HSLayers-NG should follow the Angular style guide:

https://angular.io/guide/styleguide

Git workflow (detailed explanation)

  • two main branches - master and develop - and feature branches
    • master for stable releases only
    • develop for testing and combining new features
  • create branches for new features named either after the feature purpose (e.g. geolocation, vector-tiles) or preferably the issue number (e.g. issue-121) or e.g. hotfix branch.

Example of the workflow:

  1. create a new issue on GitHub to reflect the purpose of the new branch
  2. create a new branch based on develop:
git checkout develop
git checkout -b feature_branch
  1. develop new features and commit the changes (see commit guidelines on how to write a good commit message):
git commit -am "Add new supercool feature"
  1. if other changes happened on develop branch meanwhile, you need to rebase:
git fetch --all
git rebase develop

Do not skip the rebase. It is important to do a rebase first instead of merging to keep the commit history clean.

  1. resolve any conflicts during the rebase and then push the changes:
git push -u origin feature_branch
  1. merge feature_branch into develop
  • either by directly merging:
git checkout develop
git merge --ff-only feature_branch
  • or by creating a pull request for your branch if you want to have your work approved by others

Commit messages

We follow the conventional commits guidelines.

For additional formatting of commit messages see Chris Beams blog and tbaggery blog

Seven rules of a good commit message:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

For example:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Release workflow

We make public releases to GitHub and npm.

Before releasing

If there is a demand for a new release, the developer then

  1. provides a complete list of changes for the new release
  2. creates a Pull request from develop to master
  3. notifies one of the testers about it

The tester then

  1. creates a ticket with list of features for testing in Trello (as a check-list)
  2. does the actual testing – see Testing
  3. moves the Trello ticket to "Done"
  4. approves the Pull request

Either of those can make the actual public release then.

Creating the release

The easy way of making a new public release is to use release-it which is also included in devDependencies. In order to automatically create a release with bundled files as assets on GitHub, you must provide a GitHub access token first.

Copy .env.example file and rename it to .env. Then obtain a GitHub access token as described here and fill it in the .env file.

Then just run:

npm run release

Note: never forget to run npm run build or similar command before release!

Without further settings, this will create new release on GitHub and publish the new version in npm.

After releasing

When the changes goes public, the tester makes a fresh install of hslayers-ng from npm and checks that everything works as expected.

If you want to develop hslayers-ng and have a project which uses hslayers-ng at the same time, do a symlink to you local hslayers repository. Execute npm link inside hslayers-ng directory and then npm link hslayers-ng inside your projects directory. See Set up a dev environment for more dev tips.