Guidelines

General

If you're interested in contributing please follow these guidelines:

1. If you haven't done so already we recommend creating a Github account and making a personal fork of the libraries.

2. After making a local clone of your personal fork it's a good idea to add "remotes" pointing to the personal forks of other developers you're interested in tracking. This allows you to merge in their changes if needed.

3. Check the issues page or the milestones page and look for something you'd be interested in working on.

4. Once you've picked something, "assign" yourself to the issue to let others know you're working on it. This prevents replication of efforts. If you can't find something, consider adding a primitive using the guidelines outlined in the next section.

5. When you think you're done, remember to push your changes to a topical branch (i.e. a branch with a meaningful name) on your personal fork and submit a pull request. It's also recommended that you run the test suite at this point to ensure nothing has been broken.

6. Finally, remember to check your pull request often to answer questions and possibly submit more commits to it.

Adding a primitive

In addition to the above general guidelines if you'd like to add a block to the primitives library we recommend following these procedures:

1. Create a new milestone on the milestones page with the name of the primitive you'd like to add, for example "Concat primitive needed." If you do not have permissions to do this (i.e. you don't see a "Create milestone" button anywhere) then make a separate issue asking for a milestone to be created, and please reference the issues you create below.

2. Add at least four issues, one for each of the files required. These issues should each reference the needed file and optionally make recommendations on how to implement them. Having separate issues within a milestone makes it very easy for developers to track progress for each primitive and discuss them in a structured way. Below is a list of required files per primitive (please replace <block> with the name of the proposed new block):

   • libraries/primitives/<block>/<block>.py -- this file contains the Python/MyHDL model object for simulation and also functions as a wrapper that swaps in a Verilog instation when asked to convert (using toVerilog). Example: counter.py.

   • libraries/primitives/<block>/<block>.v -- this file contains the Verilog primitive description, this is the module that <block>.py instantiates during conversion. Example: counter.v.

   • libraries/primitives/<block>/<block>_tb.v -- this file is used primarily during MyHDL co-simulation and uses the MyHDL task calls, see the MyHDL Co-simulation page. Optionally, this can include a Verilog test-bench that runs when not co-simulating. Example: counter_tb.v.

   • libraries/primitives/<block>/test_<block>.py -- this file contains unit-tests following the python-nose framework. It should test as many aspects of the blocks as possible and should run the same tests for both the model in <block>.py and the actual primitive in <block>.v using co-simulation. Example: counter.py.

3. Add any additional issues you feel are important to this specific primitive. Feel free too add as many issues as you want! Just make sure to link them with the primitive's milestone.

4. Assign the 'primitives' label to all your issues and add any other labels you feel are relevant. Labels allow other developers to narrow down their searches when looking for issues to work on.

5. If you're going to be the one writing this primitive assign yourself to all issues in the milestone. Or only a few, or none at all if you'd like someone else to work on it.