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. Please follow the steps below to setup your account.
* [Signup](https://gitlab.softwareheritage.org/users/sign_up) to create a new gitlab user and wait for approval
* Once approved, you will get a notification
* If you are not already, familiarize with git and [gitlab](https://docs.gitlab.com/ee/tutorials/make_your_first_git_commit.html)
* Setup [ssh keys](https://docs.gitlab.com/ee/user/ssh.html) to communicate with Gitlab
* Setup [ssh keys](https://docs.gitlab.com/ee/user/ssh.html) to communicate with SWH Gitlab
* [Optional] Install gitlab cli tools
* Sign the Software Heritage Contributor License Agreement
## 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 even a small edit in the code, please adhere to the steps below
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
* 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)
* Make commits following the [SWH best practices](https://docs.softwareheritage.org/devel/contributing/python-style-guide.html)
* Push your branch to your forked repository
* Create a merge request against the SWH project master branch
* Create a merge request against the master branch in the SWH repository
* Make sure the merge request passes all the steps in the 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
------------------
A [script](https://gitlab.softwareheritage.org/swh/devel/swh-environment/-/blob/master/bin/fork-gitlab-repo) using 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. The workflow using this quick start script is as follows:
A [script](https://gitlab.softwareheritage.org/swh/devel/swh-environment/-/blob/master/bin/fork-gitlab-repo) using 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
Configure your python-gitlab access token
This is required because <>
Install python-gitlab
```
How to get the access token
$ pip install python-gitlab
```
If you haven't done already, checkout the swh-environment. Refer to the <running SWH locally> document for details
Create an access token with api and write repository scopes [here](https://gitlab.softwareheritage.org/-/profile/personal_access_tokens)
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
```
[swh]
url = https://gitlab.softwareheritage.org
private_token = <your generated token>
api_version = 4
```
If you haven't done already, setup the swh-environment. Refer to the <running SWH locally> document for details
[swh-objstorage](https://gitlab.softwareheritage.org/swh/devel/swh-objstorage) is used as an example here. Replace that with the repository you wish to work
Run the script by
```
$ cd swh-environment
$ bin/fork-gitlab-repo -g swh <project name eg:swh-objstorage>
```
Run the script
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).
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. Apart from that, the script will add an extra git remote called 'forked' which can be used to pull update from the original SWH repository.
