General Development Workflow
This document aims to explain the steps component developers would have to perform on daily basis from forking the project to merging a change, emphasising on the Github workflow.
1. Fork the UI5 Web Components repository.
See how to fork a repo here.
2. Clone the UI5 Web Components repository.
See how to clone a repo here.
3. Run the project.
3.0. Make sure you have the following prerequisites installed:
3.1. Install all dependencies.
3.2. Build and serve the project.
Once the project is served, you can explore the components on:
- http://localhost:8080/test-resources/pages/ for the
- http://localhost:8081/test-resources/pages/ for the
- http://localhost:9191/test-resources/pages/ for the
The server will reload the pages whenever you make changes in the code.
Note: If these ports are unavailable to be opened, then the pages will be served on the next available ports. See the console output for the available URLs.
4.1. Read the dedicated tutorials for component developers:
- Development Conventions and Guidelines;
- Developing Custom UI5 Web Components;
- Testing UI5 Web Components;
- Understanding UI5 Web Components Metadata.
4.2. Create a local branch within your fork and work with it as usual.
4.3. Before committing, run the linter to check if your code is written according to the project eslint configuration.
$ yarn lint
4.4. Before committing, run the test of the component you are working on (see the article for testing above) to catch issues as soon as possible.
$ cd packages/main $ yarn test test/specs/Button.spec.js
5. Open pull request (PR) from fork.
You can open a pull request to the upstream repository from any branch or commit in your fork. We recommend that you make changes in a topic branch (not in your local master), so that you can push followup commits if you receive feedback on your pull request.
You can open a pull request from the Github UI.
5.1. Find the “Pull requests” tab and then press the “New pull request” button.
5.2. Compare the master branch of the upstream with a branch from your fork.
Note: The full guide on how to open PR from fork can be found here.
5.3. Once the PR is created you would have to accept a Developer Certificate of Origin (DCO). Just follow the link posted in the PR by the CLA assistant.
Note: This is required only for your first PR.
5.4. Immediately after the PR is created, a central build process starts to verify the change, building the project and running all tests. In case you are interested in the build output, you can follow the link at the bottom of the PR page, called “continuous-integration/travis-ci/pr”.
5.5. Wait for our code review and approval. After the PR is approved, the UI5 Web Components team will merge the change into the master.
6. Update pull request, created from a fork.
You often would need to update your pull request, especially when you need to address review comments. To update your pull request, you have to push commits to the branch, that the pull request is based on and the changes will be reflected in the pull request.
Note: We recommend syncing your fork before pushing commits to resolve merge conflicts beforehand.
Note: The full guide on how to update PR can be found here.
7. Sync the fork.
With the time your fork will be out of sync with the original repository and you would need to update it.
7.1. Specify a new remote upstream repository that will be synced with the fork.
$ git remote add upstream https://github.com/SAP/ui5-webcomponents.git
7.2. Fetch the branches and their respective commits from the upstream repository. Commits to master will be stored in a local branch, upstream/master.
$ git fetch upstream
7.3. Check out your fork’s local master branch.
$ git checkout master
7.4. Merge the changes from upstream/master into your local master branch. This brings your fork’s master branch into sync with the upstream repository, without losing your local changes.
$ git merge upstream/master
Note: The full guide on how to sync a fork can be found here.