Improve developer documentation and experience #184
Conversation
CONTRIBUTING.md
Outdated
| @@ -2,7 +2,9 @@ | |||
|
|
|||
| We welcome contributions to the project in any form, including bug reports, bug fixes, new features, improved documentation, or improved test coverage. | |||
|
|
|||
| Developer-specific documentation is available at https://roualdes.github.io/bridgestan/latest/internals.html | |||
| **Developer-specific documentation is available at [as part of our online documentation](https://roualdes.github.io/bridgestan/latest/internals.html)**. Information on building BridgeStan, running tests, and developing with the project is available there. | |||
There was a problem hiding this comment.
I prefer links to be minimal nouns or noun phrases, so I would use as part of our [online documentation](...), though it could be as part of [our online documentation](...) or even as [part of our online documentation](...).
| Developer-specific documentation is available at https://roualdes.github.io/bridgestan/latest/internals.html | ||
| **Developer-specific documentation is available at [as part of our online documentation](https://roualdes.github.io/bridgestan/latest/internals.html)**. Information on building BridgeStan, running tests, and developing with the project is available there. | ||
|
|
||
| This document houses additional information about licensing and procedures for contributing to the project. |
There was a problem hiding this comment.
houses -> contains OR supplies OR provides, because there's no housing, so it's distracting.
| C++ | ||
| --- | ||
|
|
||
| * We use the C++1y standard for compilation (``-std=c++1y`` in both clang and gcc). This is partway between C++11 and C++14, and is what Stan requires. |
There was a problem hiding this comment.
As of R 4.3, they support C++17. It rolled out earlier this year with a late 4.2.x. See https://developer.r-project.org/blosxom.cgi/R-devel/NEWS/2023/01/27#n2023-01-27
I don't know if Python is a blocker.
There was a problem hiding this comment.
Because we don't rely on any specific C++ ABI, we could use any C++ standard we like for this project. This comment is just there because it's what our makefiles pass and what the rest of Stan uses
|
|
||
| * We try to follow the `Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html>`_, but (a) we allow C++ exceptions, and (b) we allow reference arguments. | ||
|
|
||
| * We recommend using `Clang format <https://clang.llvm.org/docs/ClangFormat.html>`_ with our config file `.clang-format <https://github.com/roualdes/bridgestan/blob/main/.clang-format>`_. |
There was a problem hiding this comment.
I think this line's too long. I think it's OK to wrap even with bullets.
|
Sorry--I didn't see @roualdes approving this or I wouldn't have added other picky comments (though I would still prefer to see the syntax of what's included in links be a noun). |
.pylintrcinpython/a bit more useful for our project (we still don't enforce this anywhere)