> ## Documentation Index
> Fetch the complete documentation index at: https://easyaf.nimbleapps.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribution Guidelines

> Learn how to contribute to the Restier project

# How Can I Contribute?

There are many ways for you to contribute to RESTier. The easiest way is to participate in discussion of features and issues. You can also contribute by sending pull requests of features or bug fixes to us. Contribution to the [documentation](http://odata.github.io/RESTier/) is also highly welcomed.

> [card] Discussion
>
> Participate in discussions and ask questions about RESTier at our [GitHub issues](https://github.com/OData/RESTier/issues).

> [card] Bug Reports
>
> Report bugs using the issue template. Issues related to other libraries should be reported to their respective trackers.

> [card] Pull Requests
>
> Submit pull requests for features, bug fixes, and documentation improvements.

## Discussion

You can participate in discussions and ask questions about RESTier at our [GitHub issues](https://github.com/OData/RESTier/issues).

## Bug Reports

> [!WARNING]
>
> When reporting a bug at the issue tracker, fill the template of the issue. Issues related to other libraries should not be reported in RESTier library issue tracker, but be reported to other libraries' issue tracker.

## Pull Requests

> [!NOTE]
>
> **Pull request is the only way we accept code and document contribution.** Pull requests for documentation, features, and bug fixes are all welcomed. Refer to this [link](https://help.github.com/articles/using-pull-requests/) to learn details about pull requests. Before you send a pull request to us, you need to make sure you've followed the steps listed below.

### Pick an issue to work on

**1. Find or create an issue**

You should either create or pick an issue on the [issue tracker](https://github.com/OData/RESTier/issues) before you work on the pull request.

**2. Wait for approval**

After the RESTier team has reviewed this issue and changed its label to "accepting pull request", you can work on the code change.

### Prepare Tools

> [tab] Documentation
>
> * [Atom](https://atom.io/) with package [atom-beautify](https://atom.io/packages/atom-beautify) and [markdown-toc](https://atom.io/packages/markdown-toc)
> * [MarkdownPad](http://www.markdownpad.com/)

> [tab] Code
>
> * Visual Studio 2015 or later

### Steps to create a pull request

These are the recommended steps to create a pull request:

**1. Fork the repository**

Create a forked repository of [https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git)

**2. Clone locally**

Clone the forked repository into your local environment

**3. Add upstream remote**

Add a git remote to upstream for local repository:

```bash theme={"dark"}
git remote add upstream https://github.com/OData/RESTier.git
```

**4. Make code changes**

Make code changes and add test cases (refer to Test specification section for more details about tests)

**5. Test your changes**

Test the changed code with one-click build and test script

**6. Commit changes**

Commit changed code to local repository with clear message

**7. Rebase with upstream**

Rebase the code to upstream and resolve conflicts if any:

```bash theme={"dark"}
git pull --rebase upstream master
# If conflicts exist:
git pull --rebase continue
```

**8. Push to fork**

Push local commit to the forked repository

**9. Create pull request**

Create pull request from forked repository Web console via comparing with upstream

**10. Complete CLA**

Complete a Contributor License Agreement (CLA), refer below section for more details

**11. Review process**

Pull request will be reviewed by Microsoft OData team

**12. Address feedback**

Address comments and revise code if necessary. Commit the changes to local repository or amend existing commit:

```bash theme={"dark"}
git commit --amend
```

**13. Rebase again**

Rebase the code with upstream again and resolve conflicts if any:

```bash theme={"dark"}
git pull --rebase upstream master
# If conflicts exist:
git pull --rebase continue
```

**14. Test again**

Test the changed code with one-click build and test script again

**15. Push updates**

Push changes to the forked repository (use `--force` option if existing commit is amended)

**16. Merge**

Microsoft OData team will merge the pull request into upstream

### Test specification

All tests need to be written with **xUnit**. Here are some rules to follow when you are organizing the test code:

> [accordion] Project name correspondence
>
> Format: `X -> X.Tests`
>
> For instance, all the test code of the `Microsoft.Restier.Core` project should be placed in the `Microsoft.Restier.Core.Tests` project.
>
> **Path and file name correspondence**: `X/Y/Z/A.cs -> X.Tests/Y/Z/ATests.cs`
>
> For example, the test code of the `ConventionBasedApiModelBuilder` class (in the `Microsoft.Restier.Core/Convention/ConventionBasedApiModelBuilder.cs` file) should be placed in the `Microsoft.Restier.Core.Tests/Convention/ConventionBasedApiModelBuilderTests.cs` file.

> [accordion] Namespace correspondence
>
> Format: `X.Tests/Y/Z -> X.Tests.Y.Z`
>
> The namespace of the file should strictly follow the path. For example, the namespace of the `ConventionBasedApiModelBuilderTests.cs` file should be `Microsoft.Restier.Core.Tests.Convention`.

> [accordion] Utility classes
>
> The file for a utility class can be placed at the same level of its user or a shared level that is visible to all its users. But the file name must **NOT** end with `Tests` to avoid any confusion.

> [accordion] Integration and scenario tests
>
> Those tests usually involve multiple modules and have some specific scenarios. They should be placed separately in `X.Tests/IntegrationTests` and `X.Tests/ScenarioTests`. There is no hard requirement of the folder structure for those tests. But they should be organized logically and systematically as possible.

### Complete a Contribution License Agreement (CLA)

> [!NOTE]
>
> You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright.

Please submit a Contributor License Agreement (CLA) before submitting a pull request:

**1. Download the agreement**

\[Download the Microsoft Contribution License Agreement]\([https://github.com/odata/odatacpp/wiki/files/Microsoft](https://github.com/odata/odatacpp/wiki/files/Microsoft) Contribution License Agreement.pdf)

**2. Sign and scan**

Sign the agreement and scan it

**3. Email to Microsoft**

Email the signed agreement to [cla@microsoft.com](mailto:cla@microsoft.com)

> [!TIP]
>
> Be sure to include your GitHub username along with the agreement.

> [!NOTE]
>
> Only after we have received the signed CLA will we review the pull request that you send. You only need to do this once for contributing to any Microsoft open source projects.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.