azure-storage-cpp/CONTRIBUTING.md

If you intend to contribute to the project, please make sure you've followed the instructions provided in the [Azure Projects Contribution Guidelines] (http://azure.github.io/guidelines/).

Project Setup on Windows

On Windows, the Azure Storage development team uses Visual Studio so instructions will be tailored to that preference. However, any preferred IDE or other toolset should be usable.

Install

• Visual Studio 2015 or Visual Studio 2013 with C++ toolsets.
• Clone the source code from GitHub.

Open Solution

Open the project from Visual Studio using File->Open->Project/Solution... and navigate to the Microsoft.WindowsAzure.Storage.v140.sln (for Visual Studio 2015) or Microsoft.WindowsAzure.Storage.v120.sln (for Visual Studio 2013) solution file in the repo base folder. The dependent library Casablanca will be installed by NuGet upon building.

Tests

Add Unit Test Project

Use Visual Studio menu File->Add->Existing Project... and navigate to the folder Microsoft.WindowsAzure.Storage\tests. Select Microsoft.WindowsAzure.Storage.UnitTests.v140.vcxproj (for Visual Studio 2015) or Microsoft.WindowsAzure.Storage.UnitTests.v120.vcxproj (for Visual Studio 2013).

Install UnitTest++

• Fetch source code of UnitTest++ from its [GitHub repo] (https://github.com/unittest-cpp/unittest-cpp)
• Checkout version 1.4

git checkout v1.4

• Create a folder UnitTest++ under Microsoft.WindowsAzure.Storage\tests and copy all contents of unittest-cpp to it.
• Add another existing project to the Visual Studio via File->Add->Existing Project.... Navigate to Microsoft.WindowsAzure.Storage\tests\UnitTest++, and select UnitTest++.vsnet2005.vcproj.
• A "Review Project And Solution Changes" dialog popups. Choose OK, and a new UnitTest++.vsnet2005.vcxproj is generated and added to the solution.

Configuration

The only step to configure testing is to change the test_configuration.json file in Microsoft.WindowsAzure.Storage\tests folder. You should insert your storage account information into the file. If you want to run the tests against Azure Storage Emulator, change target to devstore. If you want to run the tests against real Azure Storage, use real connection string in production.

Running

Set Microsoft.WindowsAzure.Storage.UnitTests as startup project. You can specify a subset of tests to run on the command line before running the project. Go to the project properties for the unit test project, select Configuration Properties-> Debugging->Command Arguments. Enter a space-separated list of SUITE:TEST and/or SUITE. For example: Queue:Queue_Messages, Core, or Table TableClient.

Debug

To use Fiddler, you need to set the system winhttp proxy. Open an administrator command prompt. Run netsh.exe. Set the proxy by executing the command: winhttp set proxy localhost:8888. Clear the proxy by executing the command: winhttp reset proxy.

Project Setup on Linux

The Azure Storage development team uses Ubuntu 14.04 LTS as the main development platform, so instructions will be tailored to that. However, you can refer to other platforms' documentation to install the dependent libraries and preferred IDE or other toolset.

Casablanca

Azure Storage Client Library for C++ depends on Casablanca. Follow these instructions to compile and install it.

Additional Dependencies

sudo apt-get install libxml++2.6-dev libxml++2.6-doc uuid-dev

Build

cd azure-storage-cpp/Microsoft.WIndowsAzure.Storage
mkdir build.release
cd build.release
CASABLANCA_DIR=<path to Casablanca> CXX=g++-4.8 cmake .. -DCMAKE_BUILD_TYPE=Release
make

In the above command, replace <path to Casablanca> to point to your local installation of Casablanca. For example, if the file libcpprest.so exists at location ~/Github/Casablanca/cpprestsdk/Release/build.release/Binaries/libcpprest.so, then your cmake command should be:

CASABLANCA_DIR=~/Github/Casablanca/cpprestsdk CXX=g++-4.8 cmake .. -DCMAKE_BUILD_TYPE=Release

The library is generated under azure-storage-cpp/Microsoft.WindowsAzure.Storage/build.release/Binaries/.

Tests

Install UnitTest++

sudo apt-get install libunittest++-dev

Build the Test Code

CASABLANCA_DIR=<path to Casablanca> CXX=g++-4.8 cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
make

The test binary azurestoragetest and test_configuration.json are generated under the same directory as libazurestorage.so.

Configuration

The only step to configure testing is to change the test_configuration.json file in Microsoft.WindowsAzure.Storage/tests folder. You should insert your storage account information into the file. If you want to run the tests against Azure Storage Emulator, change target to devstore. If you want to run the tests against real Azure Storage, use real connection string in production.

Running

cd Binaries
./azurestoragetest [<SUITE>|<SUITE:TEST>]*

Samples

CASABLANCA_DIR=<path to Casablanca> CXX=g++-4.8 cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SAMPLES=ON
make

cd Binaries
./samplesblobs            # run the blobs sample
./samplestables           # run the tables sample
./samplesjson             # run the tables sample with json_no_metadata to reduce payload size
./samplesqueues           # run the queues sample

Pull Requests

Guidelines

The following are the minimum requirements for any pull request that must be met before contributions can be accepted.

• Make sure you've signed the CLA before you start working on any change.
• Discuss any proposed contribution with the team via a GitHub issue before starting development.
• Code must be professional quality.
  • You should strive to mimic the style with which we have written the library.
  • Clean, well-commented, well-designed code.
  • Try to limit the number of commits for a feature to 1-2. If you end up having too many we may ask you to squash your changes into fewer commits.
• Changelog.txt needs to be updated describing the new change.
• BreakingChanges.txt contains changes that break backward-compatibility.
• Thoroughly test your feature.

Testing Features

As you develop a feature, you'll need to write tests to ensure quality. You should also run existing tests related to your change to address any unexpected breaks.

Branching Policy

Changes should be based on the dev branch. We're following semver. We generally release any breaking changes in the next major version (e.g. 1.0, 2.0) and non-breaking changes in the next minor or major version (e.g. 2.1, 2.2).

Adding Features for All Platforms

We strive to release each new feature for each of our environments at the same time. Therefore, we ask that all contributions be written for both Window and Linux. This includes testing work for both platforms as well. Because most of our code is written using standard C++11 and upon a cross-platform library Casablanca, we expect contributions are also using standard language and cross-platform libraries, so that it won't cause much effort for cross-platform support.

Review Process

We expect all guidelines to be met before accepting a pull request. As such, we will work with you to address issues we find by leaving comments in your code. Please understand that it may take a few iterations before the code is accepted as we maintain high standards on code quality. Once we feel comfortable with a contribution, we will validate the change and accept the pull request.

Thank you for any contributions!

Please let the team know if you have any questions or concerns about our contribution policy.