* Install, configure, and use Git. For details, visit https://docs.gitlab.com/runner/install/
* Register an SSH public key. For details, visit https://docs.gitlab.com/ee/ci/ssh_keys/README.html#how-it-works
* Find the repository that you are interested in on the code hosting platform of |main_project_name|.
Downloading Code
****************
Forking a Code Branch from the Cloud
====================================
#. Find and open the homepage of the repository.
#. Click the Fork button in the upper right corner, and create an individual cloud fork branch as prompted.
Downloading the Fork Repository to the Local Host
=================================================
Perform the following steps to download the code in the repository to your computer:
#. Create a local working directory.
A local working directory is used for searching and managing local code.
``mkdir ${your_working_dir}``
#. Clone the remote repository to the local host.
* Switch to the local path.
``mkdir -p ${your_working_dir}``
``cd ${your_working_dir}``
|main_project_name| is an open-source project where the community can submit merge requests directly to the project. This section explains how to report a new issue, requests for enhancements and submit merge request to the project in GitLab so that your patch is merged into the source code.
* Clone the remote repository.
Changes must be committed with detailed Git commit messages. Each commit message must contain:
* You can copy the address of the remote repository on the repository page.
* Short and descriptive subject line that is less than 72 characters, the subject line must include a prefix that identifies the subsystem being changed, followed by a colon, and a short title.
* Run the following command on the local host:
* A change description with your logic or reasoning for the changes.
* A Signed-off-by line, Signed-off-by: <name> <email> typically added automatically by using git commit -s
* When editing the commit message, explain the changes and why the changes are required along with issue number.
* If the merge request addresses an issue, include a line of the form as below:
``git clone $remote_link``
.. code-block:: console
$ Fixes #<issue number>
Sign-off commit message
***********************
Committing Code
Each commit message in Pull request must be signed-off with a proper format as follows:
* To amend and add sign-off message to the previous commit, run the following command:
``git pull --rebase``
.. code-block:: console
$ git commit --amend -s
Update the local debugging branch (myfeature branch) based on the remote master branch.
* To force push your changes to GitLab commit message, run the following command:
``git branch myfeature origin/master``
.. code-block:: console
``git checkout myfeature``
$ git push -f
Then, edit and modify the code in the myfeature branch
Prerequisites
*************
#. Commit the changes in the local working directory.
* To configure, install and setup your development environment of |main_project_name|, see :ref:`Getting Started <BuildOpenharmony>`.
* Create a GitLab account on https://gitlab.com/users/sign_up and have Git tools available on your development system.
* Find the repository that you are interested in on the code hosting platform of |main_project_name|.
``git add .``
For downloading tools, downloading source code, and building and running |main_project_name| image, see :ref:`Getting Started <BuildOpenharmony>`.
``git commit -m "Reason"``
Coding guidelines
*****************
You may continue to edit and test more content after the previous commit. You can use commit --amend to commit these changes.
Refer to the :ref:`Contributing Code <Contributingcode>` section of the documentation for additional details.
#. Push the changes to your remote directory.
Contribution Workflow
*********************
If you plan to review (or just establish a remote backup of your work), push the branch to your fork repository:
When contributing to the |main_project_name| Project, provide information about your change, update project documentation, and test your changes before you submit them.
``git push -f origin myfeature``
To simplify the review, merge and rebase, and to modify the commit history, perform the following contribution workflow process:
1. Click the Fork button in project repo page to create a Fork of |main_project_name| to your personal account on GitLab.
Committing Multiple Repositories (repo init/sync)
2. To work locally on an existing remote repository, clone the source files to your local computer through HTTPS or SSH, run:
#. Create an issue under any repository to be modified on Gitlab, and record the issue number (for example, #I1TVV4 in the following figure). (The issue provides a function similar to changeID of Gerrit and is used to associate multiple repositories to be modified. Skip this step if modification of multiple repositories is not involved.)
**BRANCH** indicates the local branch, **DEST_BRANCH** indicates the destination branch (trunk branch), which is usually master, and PR_CONTENT indicates the PR description. If multi-repository committing is involved, the issue number must be entered. Example:
9. Push your new branch along with the changes to your fork in personal GitLab account:
On the editing page displayed, open the comment tags for the repository, branch, and commit.
$ git push origin <branch_name>
Save the settings and exit. The repo tool automatically pushes the local branch to the remote fork repository (creates a fork repository if there is no fork repository) and generates a PR.
10. Merge a branch with master branch, run:
The tool automatically associates the PR with the issue.
.. code-block:: console
Creating a Pull Request
$ git checkout <branch_name>
***********************
$ git merge master
Access the fork repository on Gitlab, click the button for creating a PR, and select the myfeature branch to generate a PR. (Skip this step if a PR has been automatically created using the repo tool.)
For details, visit https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/#how-it-works
All the local changes are merged into the master branch.
.. Note::
.. Note::
How do I create PRs at the same time if multiple code repositories have compilation dependencies? During the development of the operating system (OS), it is common that multiple code repositories have compilation dependencies. Therefore, the PRs need to be created and merged at the same time. For this reason, Gitlab uses issues as the dependency identifiers for code repositories with compilation dependencies to commit the PRs.
For more details on using Git on the command line, see https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html.
Follow the operations below:
#. Create an issue in any of the code repositories.
#. Associate PRs that need to be built and merged at the same time with the issue.
#. After the build is triggered, the build center identifies the PRs associated with the same issue, downloads the build,
and merges the PRs into the code library after the code is approved.
Building Access Control
***********************
Creating an Issue
=================
#. Go to the homepage of the repository.
#. Click the Issues tab in the upper left corner. Then, click the issue creation button on the right, and create a dedicated task as prompted to execute continuous integration (CI) access control for associated code (feature development/bug fixing).
Associating the Issue with the PR
=================================
When creating a PR or compiling an existing PR, enter #+I+five-digit issue ID in the description box to associate the issue with the PR.
Constraints
-----------
* One PR can be associated with only one issue. Otherwise, CI cannot be triggered.
* If feature development or bug fixing involves multiple code repositories, multiple PRs can be associated with the same issue.
* Among the PRs associated with the issue, no PR that has been merged or closed is allowed. Otherwise, the CI cannot be triggered.
* If an issue has been associated with a merged or closed PR, the issue cannot be reused. In this case, create another issue and associate
it with an open PR.
Triggering Code Access Control
==============================
Comment "start build" in the PR to trigger CI access control.
If multiple PRs are associated with the same issue, the comment "start build" on any PR can trigger the CI access control of the issue.
After the access control is executed, the execution result will be automatically commented in all the PRs associated with the issue.
If the access control is passed, all PRs associated with the issue will be automatically marked as "Passed".
Reviewing Code
==============
For details, visit https://docs.gitlab.com/ee/development/code_review.html#code-review-guidelines
Related topic: `FAQs <https://git.ostc-eu.org/docs/developer-guide/-/blob/master/documentation/source/readme/FAQs.rst>`_
Upstreaming Patches via e-mail
==============================
When upstreaming work we have done to a project which uses an e-mail based workflow there might be some pitfalls along the way.
Our attribution should be in place (namingly the use of the company e-mail address as git author and maybe the signed-off-by), but sending the patches via Outlook/Exchange is not possible as the server side is known to mangle the e-mail format and patches would no longer apply.
As a solution we recommend subscribing your private e-mail address to the mailing list and using it for sending the patches. We assume here that you have done the git commit with your correct company e-mail address and git send-email is already configured to send out e-mails ([sendemail] section of .gitconfig).
To keep the correct attribution in place we need to set set the --from field to our private e-mail when executing git send-email
