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 via 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 before attempting any backports.
Run the bootstrap.sh script for your operating system from bootstrap/generated-dists/ to install build dependencies and prepare your system to build samba.
First Merge Request
Making your first merge request is straight-forward, provided you follow these steps carefully.
Obtain a GitLab.com account
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 email@example.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
Samba has coding standards, please read README.Coding in your source checkout.
Whenever participating in the Samba community, please follow and respect the guidelines in How to do Samba: Nicely
Samba Copyright Policy
Samba is a project with distributed copyright ownership, which means we prefer the copyright on parts of Samba to be held by individuals rather than corporations if possible. There are historical legal reasons for this, but one of the best ways to explain it is that it's much easier to work with individuals who have ownership than corporate legal departments if we ever need to make reasonable compromises with people using and working with Samba.
A good commit message
Good commit messages are very important. Commits should always be separated in meaningful pieces. Please make sure that your commit messages include at least the following information:
- A short summary of the fix/feature including the Samba version and component followed by a blank line.
- A more verbose description.
- A bug number if available (required for backports to a released branch, so please file a bug first)
- Your Signed-off-by tag per the Samba copyright policy
s3:smbd: Add new funky shiny and groovy feature The funky shiny and groovy feature has been added to be able to do whatever you like. A typical usecase is the following. BUG: https://bugzilla.samba.org/show_bug.cgi?id=1 Signed-off-by: Author <firstname.lastname@example.org>
Most changes to Samba should have a test to demonstrate the bug being fixed, or test the feature being added. Most tests are run using 'make test' from a Samba source tree.
- Writing Torture Tests: smbtorture in the source4/torture directory and provides direct C protocol tests.
- Writing Python Tests: If the protocol under test is DCERPC, then PIDL will have already auto-generated Python bindings. Likewise LDAP is easily accessed via LDB.
- Writing cmocka Tests: Idea for unit tests of C functions.
- LDB: Tests for LDB are in
lib/ldb/testsand are run from
Push back to GitLab and make your first merge request
Push to your repo (rather than git.samba.org, which will be origin) with:
$ git push gitlab-$USER -f
Subsequent Merge Requests (and complex first requests)
Because the Samba Team operates additional GitLab runners to support the full testsuite, we have a slightly unusual process with a single shared sandbox shared development repository, rather than the per-user fork you will have just created.
- After your first merge request has been reviewed, and now we know you are a genuine contributor, you may be granted access to the samba devel gitlab repo.
- If your first MR is complex, it is likely that your reviewer will push it again there (and link to the pipeline), or ask you to.
- If you do so, just close the original MR and open a new one, saying This replaces #123 submitted from a private fork.
Likewise, subsequent merge requests should also be made from this repository.
Use our shared development repository only to develop Samba. Don't overwrite the work of others. Prefix branches with your gitlab username, eg:
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 the 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 email@example.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 and using autobuild to merge into master
Once submitted, Samba Team members (in particular) will review your changes, and post comments to you 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!
Merging patches from GitLab (for Samba Team members)
If the developer has created a merge request, then to merge, download the patch with (eg)
Add review tags and then
git autobuild locally. The merge button
sadly doesn't work.
Merged into master as <git hash> for Samba <next version>.
See for example this closed merge request.
Mailing patches to samba-technical
The required 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 --stdout origin/master > master-featureX-01.patches.txt
The advantages to this approach is that:
- No sign-up is required to post to
samba-technical(but you will need to follow our Samba copyright policy).
The disadvantages to this approach are that:
- This is essentially a manual process at our end.
- 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: A Samba developer will submit the patch to GitLab for you and advise you of the (URL to the) results.
Please submit a merge request if you can, because the latest version of your patches become persistent in our list of outstanding merge requests and so will not be forgotten.
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.
We prefer that new patches for master are not submitted to Bugzilla alone, for similar reasons. Please submit the patches to GitLab instead (note the merge request in the URL on the bug).
Bugzilla is used however for the Release Branch Check-in Procedure.