6.1.3. Working on issues

6.1.3.1. Create a fork of ApiOpenStudio

Create a fork of ApiOpenStudio. You can then work as much as you want on that fork.

Login to GitLab and navigate to ApiOpenStudio.

Click on the Fork button on the top right of the page:

This will create a copy of ApiOpenStudio in your repository.

6.1.3.2. Set the default branch to develop

In your fork, navigate to settings -> Repository.

Set Default branch to develop.

6.1.3.3. Clone the fork

Click on Clone button on your fork, and download this to local computer and copy the clone path and clone to your computer:

6.1.3.3.1. User SSH

git clone git@gitlab.com:<my_user>/<my_repo_name>.git

6.1.3.3.2. User HTTPS

git clone https://gitlab.com/<my_user>/<my_repo_name>.git

6.1.3.4. Add ApiOpenStudio as an upstream remote

This will allow you to regularly rebase and ensure that you have the latest version of master and develop branch from the main repository:

cd /path/to/apiopenstudio
git remote add upstream git@gitlab.com:apiopenstudio/apiopenstudio.git
git fetch upstream

6.1.3.5. Create and set the SSH_PRIVATE_KEY variable got GitLab CI to use

This is required so that the GitLab CI runner can run in your fork. The runner instance needs to install the composer dependencies in order to run.

GitLab is configured to prevent any merge requests being merged until tests are passed.

This variable is safe and masked, and will never be revealed in your runner logs.

• Navigate to Settings -> CI/CD.
• Expand the Variables section.
• Click on Add Variable.
  • Enter SSH_PRIVATE_KEY in Key.
  • Generate a new private/public key, especially for this purpose. See Keygen for more details.
  • Paste the new private key into Value.
  • Uncheck the Protect variable flag. This will allow the variable to be used in the feature branch CI.
  • Click on Add Variable.
• Click on Add Variable.
  • Paste the DB root password Value.
  • Uncheck the Protect variable flag. This will allow the variable to be used in the feature branch CI.
  • Check the Mask variable flag. This will mask the variable in the logs.
  • Click on Add Variable.

6.1.3.6. Create your feature branch

Ensure that your develop branch is up-to-date with upstream/develop:

git checkout develop
git fetch upstream develop
git rebase upstream/develop
git push origin develop

Create your new feature branch:

git checkout -b feature/nn-description-of-the-feature
git push origin feature/nn-description-of-the-feature

6.1.3.7. Do your development and testing

6.1.3.8. Commit and push to your fork feature branch

Commit any changes that you've made to your branch to your origin (fork).

By prefixing your comment with #<ticket_no> (e.g. #103), the commit will be automatically added to your ticket as a comment:

git commit -a -m "#<ticket_no> <commit_comment>"
git push origin feature/nn-description-of-the-feature

6.1.3.9. Create a Merge Request

Before you make a Merge Request, ensure that you've updated the wiki and any other documentation to reflect your changes.

Click on Merge Requests in the left menu in your fork.

Click on the New merge request button.

Select your source and target branch by clicking on the Change branches link.

The target branch is always apiopenstudio/apiopenstudio develop. If you select master as your target, your merge request will be denied, and you will need to make another.

Click on Compare branches and continue.

Review your changes and submit.

6.1.3.10. Success!

Your changes will then be reviewed and hopefully merged.