How to Contribute

How To Contribute

There are lots of ways you can contribute to the bridge project:

• File a bug/issue
• Verify fixes for bugs/issues
• Submit a bug fix or feature implementation
• Submit a feature request
• Submit additional tests
• Tell others about the WinObjC project
• Submit feedback on the project
• Submit substantive documentation edits

Code Conventions

Be sure to familiarize yourself with our coding standards before contributing code fixes.

ClangFormat

In addition to the above coding standards, code should be formatted using ClangFormat.

Automated Tests

Running Tests

1. Build the entire solution (\build\build.sln)

2. Run <Root>\WinObjC\tests\Run-UnitTests.ps1.

Please note that this defaults to Debug; for Release, take a look at the command line parameters below.

Parameters

Defaults are in bold.

• -Verbosity <Verbose| Minimal >

  Output verbosity.

• -Config <Debug| Release >

  By default, Run-UnitTests defaults to Debug. Use the -Config parameter to switch to Release.

• -Platform <Win32| ARM >

  Use ARM to run tests on ARM devices. This will attempt to connect to TShell; if TShell isn't installed, the tests won't run. If no TShell connection exists, the script will attempt to establish one. By default, it will try to connect to 127.0.0.1, but you can specify an alternate IP address with the -Device parameter.

• -Device <args>

  IP of MAC address of remote device to run tests on.

• -ModuleFilter <args>

  Run only the specified set of modules. args should be valid regex of test modules to look for.

• -TestFilter <args>

  Run only the specified set of tests. args should be valid regex of tests to run.

Authoring UnitTests

1. The UnitTest project is in under build\UnitTests

2. Add test code under tests\unittests and include it into the UnitTest project

3. For more info on writing the tests, see googletest samples

Commit Guidance

Squash your change into 1 commit on top of the master branch.

For the commit message, follow the guide below:

The title is a ~50 character summary of the change.

After one blank line, add more detail about the change wrapped to ~80 
characters. If there is a github issue that is resolved by the change,
it can be added as below, with one blank line above it.

Fix #42

Contribution License Agreement

You will need to sign a Contribution License Agreement (CLA) before submitting your pull request. To complete the CLA, you will need to submit the request via the form and then electronically sign the CLA when you receive an email containing a link to the document.

This process needs to only be done once for any Microsoft open source project.

Contributing to README and Wiki

You do not need to sign a Contribution License Agreement if you are just contributing to the README or the Wiki. However, by submitting a contribution to the README or the Wiki, you are contributing it under the Creative Commons CC0 1.0 Universal Public Domain Dedication.

Directory structure

• bin/ : Various prebuilt tools
• build/ : Projects/solutions to build the SDK
• deps/ : Open source dependencies
  • prebuilt/ : Prebuilt binaries for various architectures
• Frameworks/ : Implementation of iOS-style Frameworks
• include/ : SDK headers (including headers for iOS-style Frameworks)
  • Platform/ : Headers for Windows Objective-C bindings for various OS versions
• msvc/ : Visual Studio integration files
• samples/ : Assorted samples
• tools/ : Source code to tools

Pull Request Flow

Please ensure that you fork the winobjc repository and work there before submitting a pull request. This way, your updates based on codereview or other feedback show up as updates in the same pull request.

Pre-request checklist

Please ensure the following before submitting a pull request for your changes:

• You have signed the CLA and adhered to it.
• The entire solution (\build\build.sln) builds with no errors for all flavors.
• The changed code follows our code conventions.
• The code is formatted using ClangFormat.
• New tests have been added for all new features.
• All of the automated tests pass with no failures.

After submitting a request

What happens after a pull request is submitted?

• WinObjC team reviews the change, and checks for code convention or any other issues.

• WinObjC team verifies the change passes build and automated tests with no errors.

• If the above looks good, the pull request will be accepted, and the change will be merged into the master branch. Otherwise, we will iterate over the changes with the contributor to work through any issues before accepting the pull request.