We're not perfect, and need your help - for example in the form of patches for our modules and core codebase.
### Setup your project for contributions
In contrast to running a SilverStripe website, you can't use the standard download archive for this purpose.
Our [module list on silverstripe.org](http://silverstripe.org/modules) lists the repository locations alongside
the archive downloads, typically using a version control system like "git" or "[subversion](subversion)".
General guidelines:
* Adhere to our [coding conventions](coding-conventions)
* If your patch is extensive, discuss it first on the [silverstripe forum](http///www.silverstripe.org/forums/) (ideally before doing any serious coding)
* Check your patches against the latest "trunk" or "master", as well as the latest release.
Please not that the latest stable release will often not be sufficient! (of all modules)
* Provide complete [unit test coverage](/topics/testing) - depending on the complexity of your work, this is a required
step.
* Do not set milestones. If you think your patch should be looked at with priority, mark it as "critical".
* Describe specifics on how to test the effects of the patch
* It's better to submit multiple patches with separate bits of functionality than a big patch containing lots of
changes
* Document your code inline through [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) syntax. See our
[API documentation](http://api.silverstripe.org/trunk) for good examples.
* Also check and update documentation on [doc.silverstripe.org](http://doc.silverstripe.org). Check for any references to functionality deprecated or extended through your patch. Documentation changes should be included in the patch.
* If you get stuck, please post to the [forum](http://silverstripe.org/forum) or for deeper core problems, to the [core mailinglist](https://groups.google.com/forum/#!forum/silverstripe-dev)
The core team is responsible for reviewing patches and deciding if they will make it into core. If
The SilverStripe core (`sapphire` and `cms`), as well as some of the more popular modules are in
git version control. SilverStripe hosts its modules on [github.com/silverstripe](http://github.com/silverstripe).
After [installing git](http://help.github.com/git-installation-redirect) and creating a [free github.com account](https://github.com/signup/free), you can "fork" a module,
which creates a copy that you can commit to (see github's [guide to "forking"](http://help.github.com/forking/)).
Example: [Fork the blog module](https://github.com/silverstripe/silverstripe-blog)
Now you have two choices: Smaller fixes (e.g. typos) can be edited directly in the github.com web interface
(every file view has an "edit this file" link). More commonly, you will work on a working copy on your own computer. After committing your fix, you can send the module authors a so called ["pull request"](http://help.github.com/pull-requests/).
On github, you can review outstanding [sapphire pull requests](https://github.com/silverstripe/sapphire/pulls) and [cms pull requests](https://github.com/silverstripe/silverstripe-cms/pulls)).
If you want to learn more about git, please have a look at the [free online git book](http://progit.org/book/) and the [git crash course](http://gitref.org/).
package your changes as a "patch" file. Please read the [official Subversion book](http://svnbook.red-bean.com/) (available free online) for a general introduction to subversion.
Please don't submit patch files for modules on git, as they cause us more work.
To submit a patch, [register](http://open.silverstripe.com/register) or [login](http://open.silverstripe.org/login) on open.silverstripe.org, and attach the patch to an appropriate ticket.
Please include in the comment the revision number that the patch is applicable for and a brief outline of what you fixed and how.
[Submit a patch (requires account on open.silverstripe.org)](http://open.silverstripe.com/newticket?field_type=patch&field_owner=ischommer&attachment=1)
You can create a patch file through the svn diff-command on the command-line.
More info in the [svn redbook](http://svnbook.red-bean.com/en/1.1/ch03s05.html#svn-ch-3-sect-5.3.2).
Your code editor might have a GUI for creating patches.
# in a working copy folder (e.g /myproject)
svn diff sapphire/ > ~/patch.diff
Some gotchas when using subversion and the patch format:
* Submit your patch in *diff -u* or *diff -c format*.
* If your patch involves new files, create a compressed archive for them (including any required directory-structures)
* Create patches relative to the working copy (*sapphire/main.php* instead of */Users/myuser/sapphire/main.php*)
* Remember the shortcomingsof *svn diff*: Please document moved files and created/deleted directories separately
The "[Patches: Core](http://open.silverstripe.com/report/101)" and "[Patches: Modules](http://open.silverstripe.com/report/102)" reports will let you see where all the patches are at.
We try to maintain a consistent record of descriptive commit messages. As we automatically generate changelogs from them, we need a way to categorize and filter. Please prefix **all** commit messages with one of the following tags:
*`API CHANGE`: You've added or modified the functions available to developers writing custom PHP.
*`ENHANCEMENT`: You've added something to the user-visible aspects of SilverStripe.
*`BUGFIX`: You've fixed something that was broken.
*`MINOR` Mark things that are so trivial they're not even worth telling users about; specifically, to prevent adding
clutter to our automatically generated changelogs. MINOR is not used to mark a minor bugfix or feature, see above.
Some examples:
* a subsequent commit to a bugfix/feature that you committed earlier that day
* adding unit tests (that are more interesting to developers of SilverStripe than users of it)
* In summary: if it's worth including in the changelog, it's not `MINOR`.
Further guidelines:
* Each commit should form a logical unit - if you fix two unrelated bugs, commit each one separately
* If you are fixing a ticket from our [bugtracker](http://open.silverstripe.com), please append `(fixes #<ticketnumber>)`
* If your change is related to another changeset, reference it with `r<revisionnumber>`.
* Please mention the changed classes and methods in your comment - the message should be understandable on its own without browsing any sourcecode
Example: Bad commit message
finally fixed this dumb rendering bug that Joe talked about ... LOL
also added another form field for password validation
Example: Good commit message
ENHANCEMENT Added prepValueForDB() which is called on DBField->writeToManipulation() to ensure formatting of value before insertion to DB on a per-DBField type basis (see #1234)
MINOR Added documentation for DBField->writeToManipulation() (see r55555)
<divclass="hint"markdown="1">
Note: By supplying code in patches, tickets and pull requests,
you agree that is can be used in distributions and derivative works of SilverStripe CMS and associated modules, under the BSD license.
</div>
## Reporting Security Issues
Report security issues to [security@silverstripe.com](mailto:security@silverstripe.com). Please don't file security
issues in our [bugtracker](http://open.silverstripe.org). In the event of a confirmed vulnerability in SilverStripe
core, we will take the following actions:
* Acknowledge to the reporter that we’ve received the report and that a fix is forthcoming. We’ll give a rough
timeline and ask the reporter to keep the issue confidential until we announce it.
* Halt all other development as long as is needed to develop a fix, including patches against the current and one
previous major release (if applicable).
* We will inform you about resolution and [announce](http://groups.google.com/group/silverstripe-announce) a [new
This is where most documentation should live, and is the natural "second step" after finishing the tutorials.
*Example: Templates, Testing, Datamodel*
* **Howto**: Recipes that solve a specific task or problem, rather than describing a feature.
*Example: Export DataObjects as CSV, Customizing TinyMCE in the CMS*
* **Reference**: Complements API docs in providing deeper introduction into a specific API. Most documentation
should fit elsewhere. *Example: ModelAdmin*
* **Misc**: "Meta" documentation like coding conventions that doesn't directly relate to a feature or API.
See [What to write (jacobian.org)](http://jacobian.org/writing/great-documentation/what-to-write/) for an excellent
introduction to the different types of documentation, and [Producing OSS: "Documentation"](http://producingoss.com/en/getting-started.html#documentation)
for good rules of thumb for documenting opensource software.
### Structure
* Don't duplicate: Search for existing places to put your documentation. Do you really require a new page, or just a new paragraph
of text somewhere?
* Use PHPDoc in source code: Leave lowlevel technical documentation to code comments within PHP, in [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) format.
