|
| 1 | +# Reporting a Bug |
| 2 | + |
| 3 | +If you found a bug, please create a Github issue with as much |
| 4 | +information as possible. |
| 5 | + |
| 6 | +# Requesting a Feature |
| 7 | + |
| 8 | +It is the intention of the author of this module to add helpful |
| 9 | +functions that may be used to make creating C functions parallelized |
| 10 | +with OpenMP more idiomatic for use in Perl code. |
| 11 | + |
| 12 | +If you have an idea, you may submit a feature request; but be as |
| 13 | +descriptive as possible. It is even better if you have an example |
| 14 | +implementation in the form of a Perl script. You may create an issue, |
| 15 | +then submit a Pull Request or attach the code in the Issue you creat.. |
| 16 | + |
| 17 | +# Submitting a Pull Request |
| 18 | + |
| 19 | +Please fork the repository. It is easiest to track if you create a |
| 20 | +branch named after an Issue you create on your own fork, then once |
| 21 | +you have code changes for wish you'd like feedback, submit a PR against |
| 22 | +the master branch of the main repository. |
| 23 | + |
| 24 | +If the PR is not "complete" or you're simply seeking feedback, please |
| 25 | +mark the PR as a draft. |
| 26 | + |
| 27 | +## Definition of "Complete" PR |
| 28 | + |
| 29 | +A complete PR consists of the changes, assuming the addition of the C |
| 30 | +function in the header file, and a test added in the `t/` directory. |
| 31 | + |
| 32 | +If you do not have a test, please provide a Perl script that may be |
| 33 | +used to exercise your new function or feature; if it is a change to an |
| 34 | +existing function, please update the associated tests - especially if |
| 35 | +this is to fix some kind of bug; so that we may be able to test for |
| 36 | +regressions. |
| 37 | + |
| 38 | +### `dist.ini` changes |
| 39 | + |
| 40 | +If there are additional module requirements or changes needed to the |
| 41 | +`dist.ini` file (`Dist::Zilla`,) please include those changes and some |
| 42 | +information explaining what the changes to this file affects. |
| 43 | + |
| 44 | +### Version and `Changes` changes |
| 45 | + |
| 46 | +Please update the version's minor number and include an entry in |
| 47 | +the `Changes` file that describes the changes. Part of the review |
| 48 | +process will be to adjust these, but it helps if this informatiomn is |
| 49 | +present. |
| 50 | + |
| 51 | +# Suggested Workflow |
| 52 | + |
| 53 | +It can be someone cumbersome to work with the C file that contains |
| 54 | +the macros and functions. Below are some tips to help make this process |
| 55 | +easier: |
| 56 | + |
| 57 | +1. Dist::Zilla is your friend; it's fat and bloated as all get-out; but |
| 58 | +it makes development much easier. Use it. |
| 59 | + |
| 60 | +2. Start with a driver script; better yet, start with the test script in |
| 61 | +`./t`; new functions and macros should be added under the `Inline::C` |
| 62 | +section. It is much easier to do iterative testing and development if the |
| 63 | +C code is right there in the script. Once you have verified that the C |
| 64 | +function and/or macro works, add it to the header file in share, and test |
| 65 | +with `dzil test`. |
| 66 | + |
| 67 | +## Debugging with the `.tar.gz` file from `dzil build` |
| 68 | + |
| 69 | +Do not forget, `cpanm` can install based on a `tar.gz` file, which is what |
| 70 | +the `dzil build` command creates. So you can do something like this to test |
| 71 | +a local install: |
| 72 | + |
| 73 | +1. `cpanm -U OpenMP::Simple` # removes the module if it's been _installed_ |
| 74 | +2. `dzil build` |
| 75 | +3. `cpanm OpenMP-Simple-VERSION.tar.gz` |
| 76 | + |
| 77 | +Note: if necessary, you may invoke `cpanm`'s `--notest` and `--force` flags |
| 78 | +if this is necessary for your testing or debugging situation. |
| 79 | + |
| 80 | +# Making a Release |
| 81 | + |
| 82 | +You will not have to do this, but note that the `Makefile` is for making |
| 83 | +releases. Normal contributors will not need to use the included `Makefile`. |
0 commit comments