From 240754ea4c54b5f38b2d9ff446d2b35c064007cc Mon Sep 17 00:00:00 2001 From: Eric Berquist Date: Tue, 6 Jan 2026 13:19:14 -0700 Subject: [PATCH 1/4] Update docusaurus config --- website/docusaurus.config.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index b6ed3812..77b69cdc 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -18,7 +18,6 @@ return { "repoUrl": "https://github.com/sstsimulator/sst-core" }, "onBrokenLinks": "log", - "onBrokenMarkdownLinks": "log", "presets": [ [ "@docusaurus/preset-classic", @@ -131,6 +130,9 @@ return { }, }, markdown: { + hooks: { + "onBrokenMarkdownLinks": "log" + }, mermaid: true, }, themes: ['@docusaurus/theme-mermaid'], From 60c32bcd99b1e06ba2a205c705a5e9512f9749c8 Mon Sep 17 00:00:00 2001 From: Eric Berquist Date: Thu, 15 Jan 2026 15:04:35 -0700 Subject: [PATCH 2/4] Silence more Docusaurus warnings --- website/docusaurus.config.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 77b69cdc..c42b3ef3 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -32,6 +32,8 @@ return { rehypePlugins: [(await import('rehype-katex')).default] }, "blog": { + "onInlineAuthors": "ignore", + "onUntruncatedBlogPosts": "ignore", "path": "blog" }, "theme": { From 61858e413d67f8aa39a4936cea66cd8598e525a4 Mon Sep 17 00:00:00 2001 From: Eric Berquist Date: Thu, 15 Jan 2026 15:07:31 -0700 Subject: [PATCH 3/4] Add GitHub link to clang-format-test.sh --- docs/guides/dev/contrib.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/dev/contrib.md b/docs/guides/dev/contrib.md index e6a8f62d..98f41faa 100644 --- a/docs/guides/dev/contrib.md +++ b/docs/guides/dev/contrib.md @@ -35,7 +35,7 @@ Before contributing, read the [Contributing Guide](https://github.com/sstsimulat SST-Core follows more strict developer guidelines, including code formatting and testing, than the other SST repositories. Read the [Contributing Guide](https://github.com/sstsimulator/sst-core/blob/master/CONTRIBUTING.md) before contributing. A few key notes: 1. **Discussion** Major new features require opening an issue to discuss the feature at least two weeks prior to submitting a pull request. It is helpful to include use case as well as a description of the proposed implementation. All SST community members are welcome (and encouraged) to contribute to these discussions. Early discussion of the feature helps collect use cases that can be used to make the feature more broadly useful, as well as ensure the implementation will work well with the codebase. -1. **Style** PRs must pass a clang-format check (see sst-core/scripts/clang-format-test.sh). +1. **Style** PRs must pass a clang-format check (see [sst-core/scripts/clang-format-test.sh](https://github.com/sstsimulator/sst-core/blob/master/scripts/clang-format-test.sh)). 1. **Standards** Commits must adhere to the standards outlined in the [Contributing Guide](https://github.com/sstsimulator/sst-core/blob/master/CONTRIBUTING.md) 1. **Deprecation** Changes that break public APIs (i.e., those visible to element libraries) require a [deprecation period of one major release cycle](#deprecation). 1. **Testing** New features must be accompanied by new tests. Major modifications of untested existing features should also be accompanied by tests. From 5d971cc9c5d502c342aeac710262ddbffabf5edc Mon Sep 17 00:00:00 2001 From: Eric Berquist Date: Tue, 3 Feb 2026 12:52:21 -0700 Subject: [PATCH 4/4] Start porting coding standards --- docs/guides/dev/contrib.md | 90 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/docs/guides/dev/contrib.md b/docs/guides/dev/contrib.md index 98f41faa..21b1aa88 100644 --- a/docs/guides/dev/contrib.md +++ b/docs/guides/dev/contrib.md @@ -40,6 +40,96 @@ SST-Core follows more strict developer guidelines, including code formatting and 1. **Deprecation** Changes that break public APIs (i.e., those visible to element libraries) require a [deprecation period of one major release cycle](#deprecation). 1. **Testing** New features must be accompanied by new tests. Major modifications of untested existing features should also be accompanied by tests. +#### Coding Standards +Basic coding standards, particularly C++ formatting, are handled by [clang-format](https://clang.llvm.org/docs/ClangFormat.html). A check for adherence to [the core formatting configuration](https://github.com/sstsimulator/sst-core/blob/master/.clang-format) is performed on the latest commit to every PR and must pass. To make any necessary fixes, run pre-commit or the standalone `clang-format-test.sh` script. + +##### Null and Boolean + +1. The null pointer value should be written as ```nullptr```, not ```NULL```. +1. bool values should be written as ```true``` and ```false```, not the integers zero and one (or another non-zero value). + +##### Conditionals + +1. Tests for true/false should be done without equality comparisons: + +```c++ +if (condition) return true; +``` + +1. Tests for null/non-null and zero/non-zero should be explicit: + +```c++ +if (nullptr != ptr) return; +if (0 == value) return; +``` + +1. When comparing against a constant, the constant should be the first operand: + +```c++ +if (nullptr != ptr) return; +``` + +##### Names + +1. Getters and setters in C++ classes should be uniformly named to be getFOO and setFOO, with appropriate use of ```const```: + +```c++ +std::string getFoo() const; +void setFoo(std::string const& val); +``` + +1. Variable, class, and function names should be descriptive, even if that results in a longer name. +1. Function names should start with a lower case letter and then use CamelCase (not underscores). +1. Class names should start with an upper case letter and then use CamelCase (not underscores). + +##### Header Files +For core, which uses clang-format to enforce formatting, most of these conditions are automatically enforced. + +1. All implementation files must ```#include "sst_config.h"``` before any other statements. +1. All implementation files must ```#include``` their associated header file second, just after ```sst_config.h```. For example, ```factory.c``` must include ```factory.h``` before any other headers. This helps ensure that each header file can stand on its own without silent dependencies. +1. After the config file and primary header, headers should be included in three sections and ordered alphabetical within a section: + 1. system headers + 1. core headers + 1. element library headers (if in an element library) +1. Headers should only include other headers necessary for the compilation of that header. They should not include headers only necessary for the compilation of the implementation file. +1. Whenever possible, a header should forward declare a class rather than include the header for that class [see cplusplus article](http://www.cplusplus.com/forum/articles/10627/). +1. Core header files should provide multiple-include protection with a define name of the format ```SST_CORE_
_H```. There should not be proceeding and trailing includes. + +1. Element header files should provide multiple-include protection with a define name of the format ```SST___H```. + +##### Comments + +1. Prefer comments above a statement instead of after the statement: + +```c++ +// Only create an initialization checkpoint if explicitly requested. +if (checkpoint_enabled) checkpoint(); +``` + +1. Non-trivial functions should be preceded with a comment block explaining the purpose of the function. + +```c++ +// clock tick function. Progresses the state machine one cycle. +state_machine_cpu::tick(...) +{ + ... +} + +state_machine_cpu::isDone() +{ + return (cycle < max_cycle) ? false : true; +} +``` + +1. Comments should be in sentence form. +1. Use ```FIXME: ``` without attribution to denote items which should be fixed. + +```c++ +abort(); // FIXME: The code should gracefully clean up and end simulation here. +``` + +1. All non-file local functions in the core should be commented with Doxygen comments. Doxygen comments should use the ```/**``` notation. + ### SST-Elements Guidelines Contributions to individual libraries are managed by the library owners. The application of coding standards, testing, etc. varies based on the library's maturity and usage. In general: 1. **Discussion** For large, breaking, or otherwise potentially intrusive changes, we encourage opening an issue to discuss prior to submitting a PR.