Azure SDK for C++ Contributing Guide ------------------------------------- Thank you for your interest in contributing to Azure SDK for C++. - For reporting bugs, requesting features, or asking for support, please file an issue in the [issues](https://github.com/Azure/azure-sdk-for-cpp/issues) section of the project. - If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](http://azure.github.com/guidelines.html). - To make code changes, or contribute something new, please follow the [GitHub Forks / Pull requests model](https://help.github.com/articles/fork-a-repo/): Fork the repo, make the change and propose it back by submitting a pull request. - Refer to the [wiki](https://github.com/Azure/azure-sdk-for-c/wiki) to learn about how Azure SDK for C generates lint checker, doxygen, and code coverage reports. Pull Requests ------------- * **DO** submit all code changes via pull requests (PRs) rather than through a direct commit. PRs will be reviewed and potentially merged by the repo maintainers after a peer review that includes at least one maintainer. * **DO NOT** submit "work in progress" PRs. A PR should only be submitted when it is considered ready for review and subsequent merging by the contributor. * **DO** give PRs short-but-descriptive names (e.g. "Improve code coverage for Azure.Core by 10%", not "Fix #1234") * **DO** refer to any relevant issues, and include [keywords](https://help.github.com/articles/closing-issues-via-commit-messages/) that automatically close issues when the PR is merged. * **DO** tag any users that should know about and/or review the change. * **DO** ensure each commit successfully builds. The entire PR must pass all tests in the Continuous Integration (CI) system before it'll be merged. * **DO** address PR feedback in an additional commit(s) rather than amending the existing commits, and only rebase/squash them when necessary. This makes it easier for reviewers to track changes. * **DO** assume that ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) will be used to merge your commit unless you request otherwise in the PR. * **DO NOT** fix merge conflicts using a merge commit. Prefer `git rebase`. * **DO NOT** mix independent, unrelated changes in one PR. Separate real product/test code changes from larger code formatting/dead code removal changes. Separate unrelated fixes into separate PRs, especially if they are in different assemblies. Merging Pull Requests (for project contributors with write access) ---------------------------------------------------------- * **DO** use ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) by default for individual contributions unless requested by the PR author. Do so, even if the PR contains only one commit. It creates a simpler history than "Create a Merge Commit". Reasons that PR authors may request "Merge and Commit" may include (but are not limited to): - The change is easier to understand as a series of focused commits. Each commit in the series must be buildable so as not to break `git bisect`. - Contributor is using an e-mail address other than the primary GitHub address and wants that preserved in the history. Contributor must be willing to squash the commits manually before acceptance. ## Developer Guide ### Pre-requisites This project contains Git submodules which are required to build. After cloning this repo, run `git submodule update --init --recursive`. ### CMake CMake version 3.12 or higher is required to build these libraries. Download and install CMake from the project's [website](https://cmake.org/download/). ### Vcpkg Vcpkg is required to download project dependencies. To get started, first clone vcpkg to a location on your system and run the bootstrapping script. ```sh git clone https://github.com/Microsoft/vcpkg.git cd vcpkg # Keep note of the location of this directory for the next step Windows> .\bootstrap-vcpkg.bat Linux/macOS:~/$ ./bootstrap-vcpkg.sh ``` On macOS, this command may fail if your version of the C++ toolchain is not new enough to support vcpkg. To resolve this, vcpkg recommends to install `gcc@6` from Homebrew (`brew install gcc@6`), then re-run the bootstrapping script. Next, define the `VCPKG_ROOT` environment variable and add the `vcpkg` command to your path. You will probably want to persist these changes, so it's recommended to add/edit them via the Windows "System Properties" control panel, or via your `.profile` file on Linux/macOS. > **Windows** > ```bat > set VCPKG_ROOT=C:\path\to\vcpkg > set PATH=%PATH%;%VCPKG_ROOT% > ``` > > **Linux/macOS** > ```sh > export VCPKG_ROOT=/path/to/vcpkg > export PATH=$PATH:$VCPKG_ROOT > ``` Finally, install the project dependencies with vcpkg. > **Windows** > ```bat > set VCPKG_DEFAULT_TRIPLET=x64-windows-static > vcpkg install curl[winssl] > ``` > > **Linux/macOS** > ```sh > vcpkg install curl[ssl] > ``` ### Development headers (Linux/macOS) On Linux/macOS the development headers for OpenSSL 1.1 must be installed to a location where CMake can find them. For Ubuntu 18.04 and up, you can install them directly from the main Ubuntu repository with `apt-get`. For macOS, you can install them with Homebrew. > **Linux (Ubuntu 18.04 and up)** > ```sh > sudo apt-get install libssl-dev > ``` > > **macOS** > ```sh > brew install openssl@1.1 > ``` ### Building and Testing #### Building the project First, ensure that the `VCPKG_ROOT` environment variable is set, as described [above](#vcpkg). This needs to be defined any time you want to build. Then generate the build files and build as you would any standard CMake project. From the repo root, run: ```sh mkdir build cd build cmake -Duse_default_uuid=ON .. cmake --build . ``` #### Testing the project Tests are executed via the `ctest` command included with CMake. From the repo root, run: ```sh cd build ctest -C Debug ``` ### Visual Studio 2019 You can also build the project by simply opening the desired project directory in Visual Studio. Everything should be preconfigured to build and run tests.