Difference between revisions of "Contribute"
(GitHub -> GitLab)
m (/* minor edit)
|Line 172:||Line 172:|
Signed-off-by: Author <firstname.lastname@example.org>
Signed-off-by: Author <email@example.com>
Latest revision as of 17:57, 3 January 2019
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
- Update/provide Wiki articles
- Help testing
- Report bugs
- Help to verify patches in Bugzilla
- Create patches (C developers)
- Anything else you can imagine
The Using Git for Samba Development page has details on how to prepare patches using git.
Mailing patches to samba-technical
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
Whenever participating the Samba community, please follow and respect the guidelines in How to do Samba: Nicely
How to Add/Correct Samba Documentation
Samba man pages are generated from XML sources. Providing patches based on the generated man pages does not make sense. If you would like to report typos or any other errors, you can create a bug report and point out the error(s). If you like, you can provide a patch, and earn all the Ohloh credits yourself! ;-) Instructions on creating and providing man page patches is explained below.
- Check out the current source code. Please see Using Git for Samba Development for more information on that.
- The documentation is located in the docs-xml/ subdirectory.
- All man pages, except the smb.conf man page, are located in docs-xml/manpages/. The smb.conf man page is generated out of all the files in the docs-xml/smbdotconf/ subdirectory. There are separate XML files for each parameter assorted by sections in separate subdirectories. To find an XML file for a certain smb.conf parameter, just use the 'find' command, e.g:
user@host:/data/samba/v3-4-test/docs-xml/smbdotconf> find . -name workgroup.xml ./base/workgroup.xml
- Make your changes or add documentation for a new smb.conf parameter or a new command by creating the corresponding XML file. Copying an existing file makes things a bit easier. Adapt the new file to your new parameter.
- Commit you changes to your local GIT repository using 'git commit'. Please use an appropriate commit message.
- Build the man pages running 'make manpages' in the docs-xml/ directory. Test that it works and that there are no warnings, if possible. (If you don't have a working build environment for the docs, just skip this step and comment in the bug report/on the list when publishing your patch.) See How to build Samba documentation for information on that.
- Create the patch, e.g. using 'git format-patch HEAD^..HEAD'.
- Attach this patch to the corresponding bug report or send it to the samba-technical mailing list.
- Ask for review. The reviewer will make sure that your patch will get into the affected branches.
How to Build Samba Documentation
To make sure that changes do not introduce any warnings or build errors, the man pages must be rebuilt before committing a patch. If you encounter any issues setting up a build environment, please feel free to ask!
To build the docs, the following tools are needed:
- GNU Make
- GNU autoconf
Running ./configure, tests which tools are already installed and which ones are missing. It also identifies which components can currently be built.
user@host:/data/git/samba/master/docs-xml> ./configure checking for xsltproc... xsltproc checking for rm... rm checking for inkscape... inkscape checking for inkscape... (cached) inkscape checking for inkscape... (cached) inkscape checking for inkscape... (cached) inkscape checking for inkscape... (cached) inkscape checking for inkscape... (cached) inkscape checking for inkscape... (cached) inkscape checking for pngtopnm... pngtopnm checking for pnmtops... pnmtops checking for dblatex... dblatex checking for plucker-build... no checking for html2text... html2text checking for perl... perl checking for xmllint... xmllint checking for docbook2x-texi... no checking for makeinfo... makeinfo Summary: -------------- Building the plucker versions requires : plucker-build Building the TexInfo versions requires : docbook2x-texi You will be able to build: tex ps pdf html htmlhelp htmlman3 manpages3 pearson texiinfo undocumented txt configure: creating ./config.status config.status: creating Makefile.settings config.status: creating build/catalog.xml
There are several make targets for different documentation components. Building the man pages is the most common task. To build the man pages, run the following command:
user@host:/data/git/samba/master/docs-xml> make manpages3 xsltproc --xinclude --stringparam noreference 0 --output tmp/manpages-3/cifs.upcall.8.xml xslt/expand-sambadoc.xsl manpages-3/cifs.upcall.8.xml xsltproc --output output/manpages-3/cifs.upcall.8 xslt/man.xsl tmp/manpages-3/cifs.upcall.8.xml Note: Writing cifs.upcall.8 xsltproc --xinclude --stringparam noreference 0 --output tmp/manpages-3/eventlogadm.8.xml xslt/expand-sambadoc.xsl manpages-3/eventlogadm.8.xml xsltproc --output output/manpages-3/eventlogadm.8 xslt/man.xsl tmp/manpages-3/eventlogadm.8.xml Note: Writing eventlogadm.8 xsltproc --xinclude --stringparam noreference 0 --output tmp/manpages-3/findsmb.1.xml xslt/expand-sambadoc.xsl manpages-3/findsmb.1.xml xsltproc --output output/manpages-3/findsmb.1 xslt/man.xsl tmp/manpages-3/findsmb.1.xml Note: Writing findsmb.1 [..]
After adding new XML files, you should run make clean before re-building the docs to make sure that your changes take affect.
To build the pdf files, dblatex >= 0.2.9 is needed.
How to Write Tests for Samba
Samba uses a selftest framework to check for protocol correctness and code regression errors. This framework is run using 'make test' from a Samba source tree. This framework primarily uses tests written in the Samba4 test suite smbtorture.
New tests can be added to smbtorture in the source4/torture directory. Anyone wishing to contribute new tests should first read the Writing Torture Tests Guide.
How to Provide C Patches for Samba
- You should introduce yourself on the samba-technical mailing list and join the #samba-technical IRC channel on irc.freenode.net to get in touch with other Samba developers.
- Samba uses GIT as a version control system. You should make yourself familiar with GIT. A good start for that is Using Git for Samba Development. Further GIT information can be found in the GIT tutorial.
- The Samba Developer's Guide is a good introduction into the technical stuff, even when it's not up to date.
- Samba has coding standards. To prevent superfluous work, you should read them before starting. They are summarized in the README.Coding file located in the Samba tarballs.
- If you don't know what you'd like to work on, look at the list of current bugs or check SoC/Ideas (proposals for Summer of Code projects).
- Get in communication with the Samba developers, and talk about what you want to do. This makes it easy for us to tell you "Oh, we're already working on that, you can help!" or "The best way to do that would be..." ;-)
- Checkout the latest Samba source code from GIT. You can see instructions for how to do this on the Samba development site. For new features, you always want to work against the latest master branch of Samba. To create bug fixes for a certain version, checkout the corresponding release branch. See the Samba development site for more information on current branches.
- Write some code. Make sure that your patch is as simple and small as possible and follows the Samba coding standards. And make sure that you license each file correctly.
- Test your code. Make sure it works, and run 'make test'.
- Commit the changes to your local GIT checkout using 'git commit'. Make sure to use an appropriate commit message, including the bug number if available. Create the patch using 'git-format-patch'.
- Submit your patch in Bugzilla or directly send it to the samba-technical mailing list.
- Ask for review
- Once your bug has passed review, the reviewer can commit the patch to GIT.
Samba is a huge project. Getting into it takes a certain period of time. Don't give up! ;-) Feel free to ask on all mentioned channels!
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>