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 is also highly welcomed.

Discussion

Participate in discussions and ask questions about RESTier at our GitHub issues.

Bug Reports

Report bugs using the issue template. Issues related to other libraries should be reported to their respective trackers.

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.

Bug Reports

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

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 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 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

Documentation

• Atom with package atom-beautify and markdown-toc
• MarkdownPad

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

2. Clone locally

   Clone the forked repository into your local environment

3. Add upstream remote

   Add a git remote to upstream for local repository:

   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:

   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:

    git commit --amend
    

13. Rebase again

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

    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:

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.

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.

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.

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)

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 Contribution License Agreement.pdf)

2. Sign and scan

   Sign the agreement and scan it

3. Email to Microsoft

   Email the signed agreement to [e-mail]

   Be sure to include your GitHub username along with the agreement.

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.