Skip to content

Latest commit

 

History

History
104 lines (67 loc) · 6.03 KB

CONTRIBUTING.md

File metadata and controls

104 lines (67 loc) · 6.03 KB
Raw

Contributing

Overview

Your help is highly appreciated. Thank you!

You may help via:

  • Commenting on the existing issues in the DryIoc GitHub repository.
  • Opening new issues for bugs, enhancements, and feature proposals.
  • Creating Pull Requests with the improvements, failed tests for the found bugs, and the bug-fixes.
  • Correcting the documentation errors and submitting the new documentation topics.
  • Asking and answering the questions on StackOverflow, tagging your questions with dryioc tag for easy finding.
  • Discussing the problems and ideas in the Gitter or Slack rooms.
  • Poking me on Twitter.

How to report an issue step-by-step

If you found the problem with DryIoc:

  • Please check that you are using the latest DryIoc version.
  • Create new issue with problem description.
  • To get faster feedback, faster fixes, and generally to make me happy :-)
    • Fork DryIoc
    • Add failing tests reproducing your case to test\DryIoc.IssuesTests project. Check other files in the project for general guideline, but nothing is strict here.
    • Ignore the failing tests with [Ignore("fixme")] attribute, so that CI build should pass.
    • Commit your tests and create a Pull Request for me to review.

How to build and develop the DryIoc

Build from the command line

Before sending the Pull Request please build the solution with the build.bat located in the root folder.

It will build all projects for in the Release configuration, will run unit tests and generate the documentation. Make sure that there are no project build errors or failing tests.

Develop in Visual Studio 2017+

Open DryIoc.sln solution and re-build it. If something is failing you may try to close VS, run build.bat in the root folder, open VS and try to build again.

Note: DryIoc targets multiple platforms (via msbuild project multi-targeting) which makes it slower to build. To speedup the development DryIoc has <DevMode>true</DevMode> (TODO: Point to change) MSBuild property set to true in Directory.Build.props file in the root folder. This setting minimizes the number of platforms to build - that's why you need to run build.bat to test your work for all platforms.

Productivity hint: I am using NCrunch extension to build and run the tests continuously to get an immediate feedback, quickly find regressions, and generally experiment with the code.

Develop in Visual Studio Code

DryIoc provides the friendly VSCode developing experience.

Basically you need just the C# extension installed.

Then you may run the build.bat from the shell to ensure packages are restored, code is built, tests are passing and packages are created.

You may go to the test projects in the test sub-folder and Run or Debug the tests via the editor lens provided by the extension.

Contributing to the documentation

TL;DR;

  • Edit the selected document .cs (not the .md) file in the docs\DryIoc.Docs sub-folder.
  • Run the build_the_docs.bat file from the root folder in the shell.
  • Check the updated .md file. You may preview the markdown files with the respective markdown extension in VSCode or in Visual Studio.
  • Commit the changes both for .cs and .md and follow the usual PR GitHub workflow.

Documentation in DryIoc explained

DryIoc uses the compile-able runnable documentation written in .cs C# files in the markdown format - example. That's a lot to say :-) so let me explain...

Markdown text is placed inside the /*md ... md*/ comments and the examples are just the unit test classes outside of the markdown comment blocks.

The documentation files are included into the normal NUnit test project docs\DryIoc.Docs in the DryIoc solution. This way the docs are compiled as a normal code and the example tests are up-to-date and can be run locally or on the CI side.

The documentation .cs files are converted to the markdown .md file via CsToMd Visual Studio extension and via the dotnet-cstomd dotnet CLI local tool which is already installed when you build the project. There is a CsToMd repository with more information.

When installing the extension for the Visual Studio you will see that DryIoc.Docs project has a .md files located under corresponding the .cs files.

Try edit the .cs file then save it and see that the .md file is automatically changed by the extension.

The result markdown file may be automatically previewed inside the Visual Studio with the help of Markdown Editor extension.

In VSCode you need to run the build_the_docs.bat to see the changes or just build the DryIoc.Docs project in the Debug mode (the default).