Contribute: Difference between revisions
(mention ban on git send-email) |
|||
Line 119: | Line 119: | ||
Submitting a merge request is therefore preferred, because the latest version of your patches remain persistent and will not be forgotten. |
Submitting a merge request is therefore preferred, because the latest version of your patches remain persistent and will not be forgotten. |
||
== git send-email == |
|||
Using git send-email in the Samba project is '''not permitted'''. Doing so will cause, without manual work by the recipient, your patch to be credited to '''samba-technical@...''' not your own e-mail address. |
|||
=Policies= |
=Policies= |
Revision as of 22:30, 22 May 2020
How to contribute to Samba?
Like all OpenSource projects, Samba is reliant on volunteers. You don't need special skill to help this project. Everybody can help! :-)
There are several category groups you can work on, e.g.:
- Improve documentation
- Answer user questions and triage issues on the Samba users mailing list
- Update/provide Wiki articles
- Help testing, particularly of the upcoming release or master so we find bugs before our final release.
- Report bugs in Bugzilla
- Help to verify patches in Bugzilla and in merge requests
- Create patches (C and Python developers)
- Anything else you can imagine
Submitting Patches
The preferred method for submitting patches to samba is via the official mirror on GitLab. For more information see Samba on GitLab.
Prepare your development environment
Check out a copy of Samba locally:
git clone https://git.samba.org/samba.git
You should develop new Samba features and fix bugs first in the master branch.
Run the bootstrap.sh script for your operating system from bootstrap/generated-dists/.
First Merge Request
The Using Git for Samba Development page has details on how to prepare patches using git.
Obtain a GitLab.com account
Samba development is done on GitLab.com so you will need to Register a new user account. You can sign in with you GitHub account if you have one
Fork the Samba repo (just until we get to know you)
First fork the samba GitLab.com official mirror.
In the git checkout you made earlier, add a remote for your new gitlab fork (the URL will be in the GitLab UI under the blue Clone button):
$ git remote add gitlab-$USER git@gitlab.com:$USER/samba.git
Change the 1hr default CI timeout
By default projects on gitlab.com have a 1 hour timeout set on pipelines. This must be changed in the project settings. We suggest using a timeout of 3 hours, which is still permitted on the free runners.
Otherwise, once you push your changes back, you will see errors like this:
ERROR: Job failed: execution took longer than 1h0m0s seconds
The script exceeded the maximum execution time set for the job
Prepare your patches and push back your first merge request
After preparing your patches and pushing back to your fork on gitlab.com you can submit a merge request.
Push to your repo (rather than git.samba.org, which will be origin) with:
$ git push gitlab-$USER -f
The patches will be reviewed by Samba Team members who will post comments on your merge request.
Subsequent Merge Requests
After your first merge request has been approved, you will be granted access to the samba devel gitlab repo. Subsequent merge requests should be made from this repository, because more tests are run than are possible on the free runners attached to your personal repo.
Code of conduct
Use only to develop Samba. Don't overwrite the work of others. Prefix branches with your gitlab username, eg:
$USER/topic
In return you get a full CI run using Samba Team provided resources. That in turn makes it easier for Samba Team members doing Code Review as your patches will work first time, and they can see proof of that.
If you describe your work in the branch name, this will make generating a merge request easier, as the branch name becomes the template title and allows ongoing distinct merge requests.
Step by step instructions
Add a git reference to the gitlab remote repository:
$ git remote add gitlab-ci git@gitlab.com:samba-team/devel/samba.git
Name your branch for our shared repo:
$ git checkout -b $USER/foo
Push the current branch, overwriting any other changes there:
$ git push gitlab-ci -f
Pipelines, Successful tests and Debugging CI failures
Pushing branches to samba devel gitlab repo will initiate a full CI build test.
- CI results for changes are here: Pipelines
- merge requests show a link to the Pipeline (CI) results for each patch series.
- How it works under the hood
- Debugging CI failures
Code Review
Once submitted, Samba Team members (in particular) will review your changes, and post comments to you either on your merge request. Broader discussions happen on the list, so please ensure you are subscribed to samba-technical also.
Patches from non-samba team members require a minimum of 2 reviews from samba team members prior to patches being merged.
Outside contributors are welcome to review patches also, this is a good way to learn more about Samba!
Mailing patches to samba-technical
While not ideal, submitting patches via the mailing list is possible and they may still be considered. To submit patches, use git format-patch and mail your patches to the samba-technical mailing list.
The preferred format for patch sets is a single-file bundle attached to the email you send to the list. Bundling can be automated by invoking git format-patch
with the flag --stdout
.
The disadvantages to this approach is that:
- your patches risk being missed by an interested samba team member.
- No instant feedback to you is possible regarding compilation errors and test failures
- CI testing is still required, so a Samba developer will need to submit the patch to GitLab for you
Submitting a merge request is therefore preferred, because the latest version of your patches remain persistent and will not be forgotten.
git send-email
Using git send-email in the Samba project is not permitted. Doing so will cause, without manual work by the recipient, your patch to be credited to samba-technical@... not your own e-mail address.
Policies
Regardless of how you send us your patches, please ensure you have added Signed-off-by tags to your commits, and follow the Samba copyright policy
Whenever participating in the Samba community, please follow and respect the guidelines in How to do Samba: Nicely