CONTRIBUTING.md

Contributing to SyDEVS

We're delighted that you'd like to contribute to this project. Please review the guidelines below.

Communicating possible changes

To request a feature or report a bug, please open an issue. Also, feel free to email the lead developer, Rhys Goldstein rhys.goldstein@autodesk.com, to discuss any of the following:

• Contributing a new example or simulation
• Contributing to an existing example or simulation
• Contributing to the underlying framework
• Exploring whether the framework is suitable for your application
• Exploring possible enhancements to the framework

Submitting a pull request

In general, contributors should develop on branches based off of master and pull requests should be made against master. To submit a pull request, follow the procedure below:

1. Fork and clone the repository.
2. Create a new branch based on master: git checkout -b <my-branch-name> master.
3. Make your changes, ensure the existing tests still pass; if needed add new tests and make sure they pass.
4. Push to your fork and submit a pull request from your branch to master.

Here are a few things you can do that will increase the likelihood that your pull request will be accepted:

• Follow the existing style where possible.
• Keep your change as focused as possible. If you want to make multiple independent changes, please consider submitting them as separate pull requests.
• Write a good commit message.

Adding a new unit test

The unit testing framework used in SyDEVS is Catch2. See the documentation for a tutorial and reference material. Catch2 is released under the Boost Software License 1.0. The steps below will add a new unit test:

1. cd test/unit_tests

2. Create a new source file (e.g. test_some_file.cpp) or open the appropriate existing file in your editor.

3. Add code similar to the following:

    #include <catch2/catch.hpp>
   
    TEST_CASE("test name goes here")
    {
        CHECK(2 == 3);
    }
   

4. Save the test file.

5. cd ../../bin

6. cmake ..

7. make

Adding a new regression test

The regression tests check that each selected simulation example produces the expected output. To add a new example to the regression tests, the following changes are needed:

1. Edit CMakeLists.txt to compile a new example.
2. Edit test/regression_tests/main.cpp to include the new example.
3. Add the expected output to test/regression_tests/regression_test_data in a new text file.

Documenting the Code

We are using Doxygen to build our documentation and have adopted the following policies.

• Use JavaDoc keywords. For example:

  /**
   * @brief A brief description goes here.
   *
   * @details A detailed description goes here.
   *
   * @param foo A description of the argument goes here.
   *
   * @return A description of the return value goes here.
   */
  

• Put class documentation before the class definition. For example:

  /**
   * @brief A brief description of stay_class goes here.
   *
   * @details
   * A much more detailed description of stay_classy goes here.
   */
  class stay_classy
  {
      ...
  };
  

• Put method documentation before the method declaration. For short descriptions it is acceptable to place the documentation at the end of the statement with ///<.

  /**
   * @brief A brief description of do_something goes here.
   *
   * @details
   * A detailed description of do_something goes here.
   *
   * @param foo A description of argument goes here.
   * @param bar A description of argument goes here.
   *
   * @return A description of the return value goes here.
   */
  int64 do_something(int64 foo, float64 bar);
  

  or

  int64 do_something(int64 foo, float64 bar);  ///< This is a short description
  

• To create a list in a description use the dash markdown notation. For example:

  /**
   *
   * Here's a list:
   *
   * - Item A.
   * - Item B.
   * - Item C.
   */
  

• To highlight parameters in brief or detailed descriptions use back-tick markdown notation. For example:

  /**
   * @details
   * Draw attention to the `foo` and `bar` arguments.
   */
  

• To mark source in a description use tilde-fence markdown notation. For example:

  /**
   * Example code:
   *
   * ~~~
   * int64 count = 0;
   * for (int64 index = 0; index < count; ++index) {
   *     // do something...
   * }
   * ~~~
   */