Pull Requests
All changes to source code is possible only via Pull Requests
on GitHub.
- Every pull request should be "linked" to an issue.
- Create your own fork of the repository that you wish you work on that. How to fork?
- Clone the fork - How to clone?
- Create a feature branch using git checkout command.
- Push changes to your feature branch.
- Open Pull Request on the upstream repository for review and merge. How to create a PR?.
# replace the URL with your correct clone URL.
$ git clone https://github.com/${github_user}/xpanse
git fetch --all
git checkout -b feature/my-branch
# Make your code changes.
# State your changes.
git add .
# Commit your changes.
git commit -m 'give a valid commit message'
# Push changes.
git push -u origin feature/my-branch
Multiple entry points to create PR
Once the fork is created, rest of the steps such as cloning the repository, creating feature branch, pushing to feature branch and creating PRs can be done via IDE, CLI, API, etc.
Things to remember
- Don't forget to periodically sync your fork with the upstream repository. How to sync a fork?
- Don't forget to periodically rebase your branch
git rebase -i origin/main
- If you have a group of commits related to the same change, please squash your commits into one and force push to your branch.
- Test that your change works by adapting or adding tests.
- Follow the boy scout rule to "Always leave the campground cleaner than you found it."
- Build your changes, In case of all Java applications, make sure you do a build before doing a PR. and the build has to be successful
$ mvn clean verify
- In case of xpanse UI and website, make sure the application starts without any errors and warnings:
$ npm run start
- If your PR has conflicts with the main then rebase the branch. PRs with conflicts are unlikely to be applied
- Don't change too much in a PR. The smaller the PR the easier it's to review, apply and the faster it will be done
- Even if we're monitoring closely the PR, if you think your PR doesn't move forward fast enough, don't hesitate to ping in a PR comment to get some update.
Running Linters
To ensure best code practices and uniformity within the community, we've different static code checkers, linters and code formatters used. The PR GitHub actions will fail if any of these checks fail. Hence, the developer must run these checks locally once and fix the errors highlights before pushing changes to origin.
Java Applications
- Checkstyle.
- Spotless.
mvn spotless:check && mvn checkstyle:check
# If spotless reports any errors, they can be auto corrected with the below command.
mvn spotless:apply
# If checkstyle reports any errors, they must be manually fixed by the developer.
UI
- Prettier
- ES Lint
# Prettier to automatically format all files.
npx prettier --config .prettierrc --write .
# ES Lint static checks will report errors if any and must be fixed manually.
npx eslint . --max-warnings=0
# Typescript compiler will report any TypeScript errors and must be fixed manually.
tsc
Website
In addition to the above linters mentioned in the UI, website uses vale linter for grammar and spell checks.
# Errors reported by vale linter must be fixed manually.
docker run --rm -v $(pwd)/.github/vale/styles:/styles --pull=always --rm -v $(pwd):/docs -w /docs jdkato/vale .