Create a Contribution

CODES is an open-source project and we welcome contributions from anyone that would like to be a part of it. But in order to maintain reliability, usability, and sustainability going forward there are some things that must be handled first before your pull request is merged!

Step 1: Test

1. Does your code run? Does it significantly alter the runtime performance of CODES without your code? Make a note and try to justify/identify any change in performance.

2. Because CODES runs on the ROSS engine, it is a deterministic, parallel simulation system. Your contribution must maintain all parallelism and determinism that existed prior to it. There is likely some non-deterministic features/models left in the codebase but going forward, all new code should avoid creating non-determinism where there wasn't before.

3. Write a test for your contribution. If your contribution is significant enough, it may be justifiable to create a test in the make check testing suite so that it is frequently verified.

Step 2: Reflect

1. How does your code play with other parts of CODES? Is there any ambiguity that might lead to an uninformed observer to mistakenly use your contribution when they meant to use something else?

2. Does your code alter the results of other tests and runs? Obviously there exists a case where this is unavoidable but it should be avoided unless necessary. If your code changes the results of other tests and runs, then there must be a justifiable explanation.

Step 3: Document

1. Comment your code. There's lots of people that use and tinker in the code, and we - as developers - aren't perfect and sometimes make mistakes. Commenting your code explaining what you intend for blocks of code to do can help others identify whether the written behavior is an intended feature or an unintended feature (bug).

2. Document your contribution. Create a page for the wiki explaining it! This should include high-level information about the problem it solves, how it is implemented, and where the solution came from if references exist. If you've got results, graphs, or links to papers/tech-reports, we're more than happy to see them!

3. Help others be able to use your contribution. Explain how to use it. Are there tertiary files that must be generated with a supplied script? What configuration parameters must be set?

Step 4: Create a Pull Request

0. Familiarize yourself with our git workflow design. We've based our workflow on this model: https://nvie.com/posts/a-successful-git-branching-model/. As such, your full contribution PR should be aimed to merge into the develop branch.

1. Create your pull request. Try to make your commits meaningful and descriptive, avoid making changes that aren't described in the commit. Squash or rebase your commits to clean it up.

2. Describe your pull request. What does it address (link the issue if it exists), why is it important, link to any documentation created as well.

We're working on making this process as streamlined as possible but it is a work in progress, we appreciate your help and patience!