Samba How to: Difference between revisions

From SambaWiki
(point to new markdown formatted README.Coding.md)
 
(4 intermediate revisions by 2 users not shown)
Line 28: Line 28:
= Coding Style =
= Coding Style =


When contributing to Samba, it is expected that you will follow the [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding Samba coding style guidelines]. The guidelines are about reducing the number of unnecessary reformatting patches and making things easier for developers to work together.
When contributing to Samba, it is expected that you will follow the [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding.md Samba coding style guidelines]. The guidelines are about reducing the number of unnecessary reformatting patches and making things easier for developers to work together.


Highlights of what is covered in this document:
Highlights of what is covered in this document:


* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding#quick-start Quick Start] explains the basic rules of code formatting.
* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding.md#quick-start Quick Start] explains the basic rules of code formatting.
* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding#editor-hints Editor Hints] provides basic editor settings which deal with appropriate whitespace use, etc.
* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding.md#editor-hints Editor Hints] provides basic editor settings which deal with appropriate whitespace use, etc.
* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding#faq-and-statement-reference FAQ & Statement Reference] gives examples of correct vs. incorrect code formatting.
* [https://gitlab.com/samba-team/samba/-/blob/master/README.Coding.md#faq-statement-reference FAQ & Statement Reference] gives examples of correct vs. incorrect code formatting.


= Samba codebase organization =
= Samba codebase organization =


{{:Samba codebase organization overview}}
Broadly speaking, the Samba source-code tree can be organized into the following major groups:


The Samba codebase is broken down in detail in the '''[[Samba_codebase_organization|Samba codebase organization page]]'''.
* [[Samba_codebase_organization#Top-Level_libraries|Top-level libraries]], which contains common code shared amongst the Samba processes.
* [[Samba_codebase_organization#Source3|Source3]], which is code primarily used by the file server and domain member.
* [[Samba_codebase_organization#Source4|Source4]], which is code primarily used by the Active Directory Domain Controller.
* [[Samba_codebase_organization#Infrastructure_components|Infrastructure components]], which provide the build and test framework for Samba.
* [[Samba_codebase_organization#Autogenerated_code|Autogenerated code]], which is used for parsing DCE/RPC packets as well as other regularly structured buffers.

The Samba codebase is broken down in detail in the [[Samba_codebase_organization|Samba codebase organization page]].

Latest revision as of 02:51, 13 June 2020

Development Practices

Typical development process

The typical development process on Samba looks like this:

  • A developer has a problem to solve. This might be fixing a bug, or implementing some previously unsupported Windows Server functionality.
  • The developer would then write test cases that demonstrate the problem. For server-side behaviour, these test cases would pass when run against a Windows DC, but fail against a Samba DC.
  • The finished tests are integrated into Samba’s self-test and marked as known failures initially. There are a couple of benefits to this approach:
  • It’s standard practice in Test-Driven Development (TDD) to help prove that the new test-case works correctly.
  • It means git bisect can be run over the codebase, which can help to identify any degradations introduced to Samba. After any given commit, the Samba code will always compile, and will always pass all tests.
  • The developer then writes the code to fix the bug or implement the desired functionality. The known failure status for the new tests is removed, the new tests are re-run, and this time they should all pass.
  • The developer should then run the full Continuous Integration (CI) test suite over their changes, to verify they haven’t broken any existing functionality. The Gitlab CI provides a convenient way to do this, although there are several other approaches. Developers outside the samba team can submit patches to run against the Gitlab CI by following the Merge Requests process on the Contribute page.
  • The developer should end up with a coherent set of patches that add the new functionality, along with tests that prove the new functionality works correctly. They then submit the patch-set as explained by Contribute page.
  • The code is reviewed by Samba Team members. While any developer can potentially contribute changes to the Samba codebase, only Samba Team members have the access rights to actually deliver code changes to the master code branch. Usually the reviewers provide some feedback on how the patches could be further improved.
  • Once the reviewer is happy, the code must then pass a final CI test run before it’s incorporated into the main Samba codebase.

The following sections cover the Continuous Integration and Code Review process in more detail, as these steps are particularly important to maintaining the quality of the Samba codebase.

Continuous Integration

Samba's autobuild system is the core of our CI system.

Code Review

See Samba's Code Review Guidelines

Coding Style

When contributing to Samba, it is expected that you will follow the Samba coding style guidelines. The guidelines are about reducing the number of unnecessary reformatting patches and making things easier for developers to work together.

Highlights of what is covered in this document:

Samba codebase organization

Broadly speaking, the Samba source-code tree can be organized into the following major groups:

  • Top-level libraries, which contains common code shared amongst the Samba processes.
  • Source3, which is code primarily used by the file server and domain member.
  • Source4, which is code primarily used by the Active Directory Domain Controller.
  • Infrastructure components, which provide the build and test framework for Samba.
  • Autogenerated code, which is used for parsing DCE/RPC packets as well as other regularly structured buffers.

The Samba codebase is broken down in detail in the Samba codebase organization page.