Difference between revisions of "Contribute"

(add mailing list to How to contribute to Samba?)
(change heading indent level, more content changes)
Line 1: Line 1:
== How to contribute to Samba? ==
+
= How to contribute to Samba? =
  
 
Like all OpenSource projects, Samba is reliant on volunteers.
 
Like all OpenSource projects, Samba is reliant on volunteers.
Line 14: Line 14:
 
* Anything else you can imagine
 
* Anything else you can imagine
  
== Submitting Patches ==
+
= Submitting Patches =
  
 
The preferred method for submitting patches to samba is via [https://gitlab.com/samba-team/samba the official mirror] on [https://gitlab.com/ GitLab].  For more information see [[Samba CI on gitlab]].
 
The preferred method for submitting patches to samba is via [https://gitlab.com/samba-team/samba the official mirror] on [https://gitlab.com/ GitLab].  For more information see [[Samba CI on gitlab]].
  
===First Merge Request===
+
==First Merge Request==
  
The [[Using Git for Samba Development]] page has details on how to prepare patches using git.
+
The [[Using Git for Samba Development]] page has details on how to prepare patches using git. Take particular care to
  
====Obtain a GitLab.com account====
+
===Obtain a GitLab.com account===
 
Samba development is done on [http://gitlab.com GitLab.com] so you will need to [https://gitlab.com/users/sign_in#register-pane Register a new user account].  You can sign in with you [https://github.com GitHub account if you have one]
 
Samba development is done on [http://gitlab.com GitLab.com] so you will need to [https://gitlab.com/users/sign_in#register-pane Register a new user account].  You can sign in with you [https://github.com GitHub account if you have one]
  
====Fork the Samba repo (just until we get to know you)====
+
===Fork the Samba repo (just until we get to know you)===
  
First fork the [https://gitlab.com/samba-team/samba samba git repo].
+
First fork the [https://gitlab.com/samba-team/samba samba GitLab.com official mirror].
  
By default projects on gitlab.com have a '''1 hour timeout''' set on pipelines.  This '''must be changed''' in the [https://docs.gitlab.com/ee/user/project/pipelines/settings.html project settings].
+
====Change the 1hr default CI timeout====
  
We suggest using a timeout of '''3 hours''', which is still permitted on the free runners.
+
By default projects on gitlab.com have a '''1 hour timeout''' set on pipelines.  This '''must be changed''' in the [https://docs.gitlab.com/ee/user/project/pipelines/settings.html project settings]. We suggest using a timeout of '''3 hours''', which is still permitted on the free runners.
  
Otherwise, you will see errors like this:
+
Otherwise, once you push your changes back, you will see errors like this:
  
 
  ERROR: Job failed: execution took longer than 1h0m0s seconds
 
  ERROR: Job failed: execution took longer than 1h0m0s seconds
Line 39: Line 39:
 
  The script exceeded the maximum execution time set for the job  
 
  The script exceeded the maximum execution time set for the job  
  
====Prepare your patches and push back your first merge request====
+
===Prepare your patches and push back your first merge request===
After [[Using Git for Samba Development|preparing your patches]] [https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#send-changes-to-gitlabcom pushing back to your fork on gitlab.com] and [https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html submitting a merge request], the patches will be reviewed by samba team members who will post comments on your merge request.
+
After [[Using Git for Samba Development|preparing your patches]] and [https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#send-changes-to-gitlabcom pushing back to your fork on gitlab.com] you can [https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html submit a merge request].  The patches will be reviewed by [https://www.samba.org/samba/team/ Samba Team members] who will post comments on your merge request.
  
===Subsequent Merge Requests===
+
==Subsequent Merge Requests==
  
After your first merge request has been approved, you will be granted access to the [https://gitlab.com/samba-team/devel/samba samba devel gitlab repo]. Subsequent merge requests should be made from this repository. Pushing branches to samba devel will initiate a CI build test.
+
After your first merge request has been approved, you will be granted access to the [https://gitlab.com/samba-team/devel/samba 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.
  
===Mailing patches to samba-technical===
+
===Shared development repo Code of conduct===
  
While not ideal, submitting patches via the mailing list is still considered acceptable. To submit patches, [[Using_Git_for_Samba_Development#Creating_patches_if_you_don.27t_have_write_access_to_git.samba.org_repositories|use git format-patch]] and mail your patches to the [https://lists.samba.org/mailman/listinfo/samba-technical samba-technical mailing list].
+
Please prefix branches with your gitlab username, and be nice. Use only to develop Samba. Don't overwrite the work of others.
  
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 <code>git format-patch</code> with the flag <code>--stdout</code>.
+
$USER/topic
 +
 
 +
eg
 +
 +
frednurk/kerberos-timeout-handling
 +
 
 +
In return you get a full CI run using Samba Team provided resources.  That in turn makes it easier for Samba Team members doing [[CodeReview|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 [[Samba_CI_on_gitlab#Creating_a_merge_request|generating a merge request]] easier, as the branch name becomes the template title and allows ongoing distinct merge requests.
 +
 
 +
==Pipelines, Successful tests and [[Samba CI on gitlab/Debugging CI failures|Debugging CI failures]]==
 +
 
 +
Pushing branches to [https://gitlab.com/samba-team/devel/samba samba devel gitlab repo] will initiate a full CI build test.
 +
 
 +
* CI results for changes are here: [https://gitlab.com/samba-team/devel/samba/pipelines Pipelines]
 +
* [https://gitlab.com/samba-team/samba/merge_requests|All merge requests] show a link to the Pipeline (CI) results for each patch series.  
 +
* [[Samba CI on gitlab/Under the hood|How it works under the hood]]
 +
* '''[[Samba CI on gitlab/Debugging CI failures|Debugging CI failures]]'''
  
The disadvantage to this approach is that your patches risk being missed by an interested samba team member. Submitting a merge request is preferred, because your patches become persistent and will not be forgotten.
+
=Code Review=
  
===Patch Reviews===
+
Once submitted, Samba Team members (in particular) will [[CodeReview|review your changes]], and post comments to you either on your merge request.  Broader discussions happen on the list, so please ensure you are [https://lists.samba.org/mailman/listinfo/samba-technical 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.
 
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, whether on the mailing list, or reviewing merge requests on GitLab.
+
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, [[Using_Git_for_Samba_Development#Creating_patches_if_you_don.27t_have_write_access_to_git.samba.org_repositories|use git format-patch]] and mail your patches to the [https://lists.samba.org/mailman/listinfo/samba-technical 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 <code>git format-patch</code> with the flag <code>--stdout</code>.
 +
 
 +
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.
  
===Policies===
+
=Policies=
 
Regardless of how you send us your patches, please ensure you have added [[CodeReview#commit_message_tags|Signed-off-by tags]] to your commits, and follow the [https://www.samba.org/samba/devel/copyright-policy.html Samba copyright policy]
 
Regardless of how you send us your patches, please ensure you have added [[CodeReview#commit_message_tags|Signed-off-by tags]] to your commits, and follow the [https://www.samba.org/samba/devel/copyright-policy.html Samba copyright policy]
  
 
Whenever participating in the Samba community, please follow and respect the guidelines in [[How to do Samba: Nicely]]
 
Whenever participating in the Samba community, please follow and respect the guidelines in [[How to do Samba: Nicely]]

Revision as of 21:23, 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.:

Submitting Patches

The preferred method for submitting patches to samba is via the official mirror on GitLab. For more information see Samba CI on gitlab.

First Merge Request

The Using Git for Samba Development page has details on how to prepare patches using git. Take particular care to

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.

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. 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.

Shared development repo Code of conduct

Please prefix branches with your gitlab username, and be nice. Use only to develop Samba. Don't overwrite the work of others.

$USER/topic

eg

frednurk/kerberos-timeout-handling

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.

Pipelines, Successful tests and Debugging CI failures

Pushing branches to samba devel gitlab repo will initiate a full CI build test.

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.

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