Pitcher JavaScript Platform

# Contributing

Thanks for your interest in improving the Pitcher Javascript Platform!
The Pitcher JavaScript Platform repository is a monorepo (opens new window) managed by Lerna (opens new window) and Yarn Workspaces (opens new window).

These concepts are a little hard to grasp, in order to have a better understanding about how Lerna and Yarn Workspaces work together, you can read this great article (opens new window).

The following guide is designed to get you up and running in no time.

# Setting up your environment

In order to start development you need to have:

Once you have everything installed, clone the repository:

# Using HTTPS
git clone https://github.com/PitcherAG/pitcher-js-platform.git

# Using SSH
git clone git@github.com:PitcherAG/pitcher-js-platform.git

Then install dependencies:

# Navigate to the pitcher-js-platform folder
cd pitcher-js-platform

# Install all project dependencies
yarn

# Submitting Changes / Pull Requests

The Pull Request (in short PR) is the primary method to contribute to the Pitcher Javascript Platform repository. Use Pull Requests to implement a feature or fix a bug.

We are using the Git Flow branching model. The main development branch is dev. The main branch contains the most recent stable release and hotfixes. Create a branch out of the dev repository, make the required changes, and create a Pull Request from your branch to the dev branch to change something.

Here is a summary of the steps to follow:

# 1. Create your own branch

It should adhere to the following naming convention:

  • feat/PLA-XXX-title - for features.
  • fix/PLA-XXX-title - for bug fixes.
  • docs/PLA-XXX-title - for documentation topics.
  • style/PLA-XXX-title - for style only changes.
  • refactor/PLA-XXX-title - for refactor topics.
  • revert/PLA-XXX-title - for reverting changes.

NOTE that PLA here depends on the JIRA project you have the task from. It might be APPS, TR, RK, use the one from the task you have. If your change is bound to a task on JIRA, you don't need to add a ticket number. That said, you can simply use feature/title or fix/title for example.

WARNING

Never commit directly to the base branches (main, dev), always create a feature branch to work on.

# 2. Implement changes on a package and commit your work

The monorepo contains several projects called packages e.g packages/core or packages/pitcherify.
Make sure you follow the Commit message guidelines.

INFO

If you work on i18n or core package you need to build them with yarn build after you finish with your changes. Whenever you merge changes to the dev branch, a github action will build core and i18n package on the fly and push back to dev branch.

# 4. Lint your files

Use yarn lint before pushing anything.
This will take care of any lint errors that you might have.

# 5. Create a Pull Request

Open a Pull Request (opens new window) with a clear title and description. Good pull requests, whether patches, improvements or new features should remain focused in scope and avoid containing unrelated commits.

Add at least two reviewers (opens new window) to the PR.

The Pull Request's body format is informally enforced by our PR template (opens new window) and contains 3 sections in which you:

  • reference any relevant issues or supporting documentation.
  • add the main description of the PR.
  • include screenshots of the before and after if your changes include differences in HTML/CSS. You can drag and drop the images into the body of your pull request.

# 6. Review and Approval

Once someone has reviewed your pull request, it’s common that you’ll be asked to make changes to your contribution, whether that’s feedback on the scope of your idea, or changes to your code. When you implement the changes you can re-request review from the same reviewer.
You'll need at least two review approvals in order to proceed with merging.

# 7. Merge the Pull Request

When you have the necessary approvals you can go ahead and merge the PR
using the Squash and merge (opens new window) method of GitHub.

# Commit message guidelines

Pitcher Javascript Platform uses automated version management and package publishing.
For that to work, the commit messages need to be in the right format.

# Conventional Commits

Commits should follow the Conventional Commits specification (opens new window)
The commit message should be structured as follows:

<type>[optional scope]: <description>

# Description

The description should contain succinct information about the change and follow some best practices:

  • it must not exceed 100 characters
  • first letter should be lower-case
  • no dot (.) at the end
  • include task number in the commit message if your change is depending on a JIRA task

# Revert

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

# Commit message examples

fix: stop PFileCard service from breaking when too many requests [PLA-23]

feat: PFileCard supports 'componentWidth' option [TR-202]

chore: FileCard renamed to PFileCard

docs: Documentation for PFileCard added

style: PFileCard style enhancements

refactor: PFileCard workflow simplified

revert: PFileCard supports 'componentWidth' option

BREAKING CHANGE: PFileCard component is not supported anymore

NOTE

If your change is bound to a task on JIRA, you don't need to add a ticket number. That said, you can simply use feat: my amazing feature added or fix: solves X issue with Y component for example.

# Ask for help

If you have any questions, please ask them via Slack.
Use #pitcher-vue-sdk or #technical-team channel and provide as much information as you can, just like opening an issue.

Writing documentation →