= Introduction =

Submitting a patch is a great way to contribute to Cobra. In order that patches can be applied in a timely manner, please follow these guidelines. Doing so eases the burden for those applying patches, gets your patches in faster and reduces the "apply patch" bottleneck.

Discuss the enhancement or fix ahead of time on the [http://cobra-language.com/forums/ forums] to see what others think, find out if there is already work in progress, etc.

= Coding =

See !ImplementationNotes.text in the Developer directory next door to the Source directory for information about the implementation of Cobra, how to run the test suite, etc.

Cobra supports both tabs and spaces for indentation, but the implementation of Cobra uses all tabs. Regardless of your particular religious views in this matter (or allegedly rational views), please "go with the flow" and use tabs like the rest of the implementation. Of course, in your own projects, feel free to use either or both (though not in the same line).

Cobra itself enforces some coding guidelines such as capitalizing classes and indenting code blocks. Additionally, try to mimic the style of code that you see around the code are writing. Here are some additional coding guidelines:
{{{
# Calling methods: No space after '(' or before ')'. One space after commas.
# good:
foo.bar(x, y)
# bad:
foo.bar(x,y)
foo.bar( x, y)
foo.bar(x, y )
foo.bar( x, y )

# A space before and after most binary operators most of the time.
# good:
x = 1
# bad:
a= 1
b =2
c=3

# Use augmented assignment
# good:
foo += 10
bar += 'stuff'
# bad:
foo = foo + 10
bar = bar + 'stuff'

# No extraneous parens for simple expressions:
# good:
ensure
    result in [8, 16, 32, 64]
# bad:
ensure
    (result) in [8, 16, 32, 64]

# No descriptive comments above a declaration. Use a doc string instead. Use sentences.
# good:
    def _matchBetween(input as String, start as char, stopch as char) as String?
        """
        Matches between a range of character.
        """
# bad:
    # helper for matching between a range of chars
    def _matchBetween(input as String, start as char, stopch as char) as String?

# Comments are usually lower case.
# Avoid random capitalization, random extra spaces and missing spaces.
# good:
    foo.bar  # see test case 100-basics, 400-branch.cobra
# bad:
    foo.bar  # See test  Case 100-basics, 400-branch.cobra
# good:
    .throwError('Cannot find type for "[_name]".[sugg]')
# bad:
    .throwError('Cannot find TypeFor "[_name]".[sugg]')
}}}

If you have old, commented out code that is no longer relevant due to the patch, delete it. The patch "diff" itself will show the old code and we can always retrieve it from the source code control system if we need it at a later date. Also, remove stray {{{print}}} and {{{trace}}} statements used for debugging.

Avoid `shared` variables as much as possible. Each one makes it harder to embed, reuse and multithread the Cobra compiler.

= Test Cases =

Be sure to add or update tests found in the Tests directory next door to the Source directory. You may wish to run the test suite ''before'' making your changes in order to see if there are any failures independent of them. You must run the test suite after your final changes to be sure nothing has been broken by them.

Do not use print statements in tests. Use assert statements.
{{{
# good:
assert x inherits Foo
# bad:
print 'x type =', x.getType
}}}

In test cases that should cause errors or warnings, put the "# .error." or the "# .warning." on the same line that it goes with. You'll see that many tests put these at the very top, but that was the old approach before the automated testing supported the current approach: on the same line.

After testing, if you make any small tweaks to your code, please run the test suite again. You never know what's going to break.

= Release Notes =

Update !IntermediateReleaseNotes.text in the Developer directory next door to the Source directory. Include your name or forum/Trac handle for credit. Reference tickets using Trac syntax with "ticket", colon (:) and number. (The HTML formatter for the release notes supports that.)

= Submitting =

Example:
{{{
cd CobraWorkspace
svn up
# if any changes came in, do some testing
svn add Tests/110-basics-two/520-blah-blah.cobra
svn di > FixSomething.patch
}}}

A typical patch has changes to files in Source, files in Tests and the !IntermediateReleaseNotes.text file. Please submit the patch as being rooted in the workspace directory (not in the Source subdirectory or elsewhere). This directory contains the subdirectories Source, Tests, etc.

When referring to a ticket in documentation (whether !IntermediateReleaseNotes, comments or checkin notes), use the Trac syntax of ticket:NN.

Use "svn add" on new files to get them to show up in the patch.

Submit the patch as one file which contains all changes. If later, you make additional changes, resubmit the entire patch.

Use ".patch" for the extension and otherwise, name the file as you like.

Attach the patch to a ticket instead of the forums so that it doesn't get "lost". Also, patches are a pleasure to browse in Trac, but not in phpBB. If there was a forum discussion on the topic of the patch, you can always post a link to the ticket in the discussion and vice versa.