Skip to content

Latest commit

 

History

History
116 lines (86 loc) · 6.47 KB

CONTRIBUTING.md

File metadata and controls

116 lines (86 loc) · 6.47 KB
Raw

Contributing to YamlDotNet

Welcome!
Thanks for you interest in contributing to this project. Any contribution will be gladly accepted, provided that they are generally useful and follow the conventions of the project.

If you are considering a contribution, please read and follow these guidelines.

Pull requests

All contributions should be submitted as pull requests.

  1. Please create one pull request for each feature. This results in smaller pull requests that are easier to review and validate.

  2. Avoid reformatting existing code unless you are making other changes to it.

  • Cleaning-up of usings is acceptable, if you made other changes to that file.
  • If you believe that some code is badly formatted and needs fixing, isolate that change in a separate pull request.

  1. Always add one or more unit tests that prove that the feature / fix you are submitting is working correctly.

  2. Please describe the motivation behind the pull request. Explain what was the problem / requirement. Unless the implementation is self-explanatory, also describe the solution.

  • Of course, there's no need to too verbose. Usually one or two lines will be enough.

Project organization

The main project, YamlDotNet.csproj, is organized in three main namespaces: Core, RepresentationModel and Serialization. The Core namespace contains everything that is related to reading and writing YAML. The RepresentationModel has classes that represent a YAML stream, similar to XmlDocument for XML. The Serialization namespace contains classes to serialize and deserialize object graphs to / from YAML.

Unit tests are all contained in the project named YamlDotNet.Test.csproj.

The PerformanceTests folder contains various projects that contain performance tests that compare various versions of YamlDotNet to detect the impact of new features.

Building / multiplatform

This project is available on different platforms. Solution configurations are used to select the target platform. The build.ps1 script can be used to easily build the library for all targets. Simply open a "Developer Command Prompt" and run the script:

C:\YamlDotNet> powershell .\build.ps1

Building for Unity requires installing Visual Studio Tools for Unity.

The Portable versions target Profile259. If you do not have that profile installed, a workaround is to get the reference assemblies from here and extract them to C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETPortable\v4.5\Profile\Profile259.

Configuration Target Defines Description
Debug .NET 3.5 DEBUG Default debug build.
Release-Unsigned .NET 3.5 Release build, not signed.
Release-Signed .NET 3.5 SIGNED Release build, signed.
Release-Portable-Unsigned .NET 4.5 portable Profile259 PORTABLE Portable class library, not signed.
Release-Portable-Signed .NET 4.5 portable Profile259 PORTABLE; SIGNED Portable class library, signed.
Debug-UnitySubset-v35 Unity Subset v3.5 DEBUG; UNITY Debug build for Unity target.
Release-UnitySubset-v35 Unity Subset v3.5 UNITY Release build for Unity target.

There are a few differences between the various target platforms, mainly in the reflection API. In order to adapt the code to each platform, #if ... #endif sections are used. When possible, such sections should be placed in the Helpers/Portability.cs file. An effective technique is to define an extension method that is used tourough the code, and has different implementations depending on the build variables.

AOT compatibility

Some platforms - such as IOS - forbid dynamic code generation. This prevents Just-in-Time compilation (JIT) from being used. In those cases, one can use Mono's Ahead-of-Time compilation (AOT). This results on a precompiled assembly that does not rely on JIT. There are some limitations however, most of them related to usage of generics.

In order to ensure that YamlDotNet is compatible with AOT compilation, an automatic test has been created that runs on every commit on Travis CI. That test exercises the serialize and deserializer to help identify AOT-related problems.

Coding style

Attempt to follow the SOLID principles. In particular, try to give each type a single responsibility, and favor composition to combine features.

As long as you keep the code readable, I don't care too much about any specific coding convention. There are only a few rules that should be honored:

  • Use 4 spaces to indent.
  • Each class / interface / struct / delegate goes to its own file.
    • The only acceptable exception is for small and closely related types.
  • Use sane indentation rules. Break long lines when needed, but don't be obsessive:

    • This is OK:

      Traverse(
    new ObjectDescriptor(
        value.Value,
        underlyingType,
        value.Type,
        value.ScalarStyle
    ),
    visitor,
    currentDepth
);

    • This is OK too:

      Traverse(
    new ObjectDescriptor(value.Value, underlyingType, value.Type, value.ScalarStyle),
    visitor,
    currentDepth
);

    • This is not very good:

      Traverse(new ObjectDescriptor(value.Value, underlyingType, value.Type, value.ScalarStyle), visitor, currentDepth);

    • This is awful:

      Traverse(new ObjectDescriptor(value.Value,
                              underlyingType,
                              value.Type,
                              value.ScalarStyle),
         visitor,
         currentDepth);