We use [gitlab](https://gitlab.softwareheritage.org/) ([Community Edition](https://gitlab.com/gitlab-org/gitlab-foss)) as the coding/collaboration forge.
We use `gitlab <https://gitlab.softwareheritage.org/>`__ (`Community
Edition <https://gitlab.com/gitlab-org/gitlab-foss>`__) as the
coding/collaboration forge.
For a new contributor
For a new contributor
---------------------
---------------------
You will need an account in SWH gitlab for contributing code or documentation. Please follow the steps below to setup your account.
You will need an account in SWH gitlab for contributing code or
documentation. Please follow the steps below to setup your account.
* [Signup](https://gitlab.softwareheritage.org/users/sign_up) to create a gitlab account.
* Account approve and land is manual and could take a while. Once approved, you will get a notification.
- `Signup <https://gitlab.softwareheritage.org/users/sign_up>`__ to
* If you are not already, familiarize with [git](https://git-scm.com/book/en/v2) and [gitlab](https://docs.gitlab.com/ee/tutorials/make_your_first_git_commit.html).
create a gitlab account.
* Setup [ssh keys](https://docs.gitlab.com/ee/user/ssh.html) to communicate with SWH Gitlab.
- Account approve and land is manual and could take a while. Once
* Sign the Software Heritage Contributor License Agreement. Please contact us to know more about this.
- Setup `ssh keys <https://docs.gitlab.com/ee/user/ssh.html>`__ to
communicate with SWH Gitlab.
- Sign the Software Heritage Contributor License Agreement. Please
contact us to know more about this.
Development workflow
Development workflow
--------------------
--------------------
We use a [fork based workflow](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) and [merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/) for code contributions. In order to submit a feature or for any edits in the code, please adhere to the steps below:
* Create a fork of the project you wish to contribute to in your personal namespace.
and `merge
* Clone your forked repository and start working. It is strongly recommended to work on a [feature branch](https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html).
- Create a merge request against the SWH repository.
- Make sure the merge request passes the CI build.
- Address the review comments, if any, and wait for an approval.
- Once approved, a team member will merge your changes to the master
branch.
Quick start script
Quick start script
------------------
------------------
note: If you haven't done already, setup the swh-environment before this. Refer to the <running SWH locally> document for details.
note: If you haven’t done already, setup the swh-environment before
this. Refer to the :ref:`getting started <getting-started>` for details.
A [script](https://gitlab.softwareheritage.org/swh/devel/swh-environment/-/blob/master/bin/fork-gitlab-repo) using [python-gitlab](https://github.com/python-gitlab/python-gitlab) is available to partially automate the above workflow. Using this script is recommended as it simplifies the complexities associated with the build pipelines and multiple remotes. You can use the script by following the steps below:
A `script <https://gitlab.softwareheritage.org/swh/devel/swh-environment/-/blob/master/bin/fork-gitlab-repo>`__
using `python-gitlab <https://github.com/python-gitlab/python-gitlab>`__
is available to partially automate the above workflow. Using this script
is recommended as it simplifies the complexities associated with the
build pipelines and multiple remotes. You can use the script by
following the steps below:
Create an access token with api and write repository scopes [here](https://gitlab.softwareheritage.org/-/profile/personal_access_tokens).
Create an access token with api and write repository scopes
The script will use this token to create a fork in your namespace and to add jenkins as a user with developer permissions.
Create or update the config file ``~/.python-gitlab.cfg`` and add the following content.
The script will use this token to create a fork in your namespace and to
add jenkins as a user with developer permissions. Create or update the
config file :file:`~/.python-gitlab.cfg` and add the following content.
```
.. code-block::
[swh]
url = https://gitlab.softwareheritage.org
private_token = <your generated token>
api_version = 4
```
In the following command line excerpts, we will use [swh-objstorage](https://gitlab.softwareheritage.org/swh/devel/swh-objstorage) as example. Please, replace that with the repository you wish to work with.
[swh]
url = https://gitlab.softwareheritage.org
private_token = <your generated token>
api_version = 4
In the following command line excerpts, we will use
Switch to your local copy that is now ready for code contributions. You
can find an extra remote named ‘forked’. This points to your forked
repository and that can be used to push your changes.
This will create a new fork of the SWH repository in your namespace and add a jenkins user to perform automatic builds. You can view the forked project in your personal projects [here](https://gitlab.softwareheritage.org/users/<username>/projects).
.. code-block::
Switch to your local copy that is now ready for code contributions. You can find an extra remote named 'forked'. This points to your forked repository and that can be used to push your changes.
