Skip to content

More December docs sync #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
neatudarius merged 2 commits into from
Dec 24, 2025
Merged

More December docs sync #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
62c75be
More December docs sync
Dec 15, 2025
67dc9a6
Also sync binaries
Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 32 additions & 31 deletions docs/beman_standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ needs. To make changes:
1. Create a [discourse topic](https://discourse.boost.org) detailing the change
and how it aligns with the core principles.
2. After some community discussion, create a PR with the actual change on
[GitHub](https://github.com/bemanproject/beman) and apply the **Beman leads** label.
[GitHub](https://github.com/bemanproject/beman) and apply the *Beman leads* label.
The PR should also link to the discourse topic.
3. Continue discussions on the PR and discourse topic.
4. Await a leads decision based on the community feedback.
Expand Down Expand Up @@ -68,7 +68,6 @@ recommendations.

1. [Apache License v2.0 with LLVM Exceptions](https://llvm.org/LICENSE.txt)
2. [Boost Software License 1.0](https://www.boost.org/LICENSE_1_0.txt)
3. [The MIT License](https://opensource.org/license/mit)
Copy link
Member Author

@neatudarius neatudarius Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JeffGarland , I think this is the only relevant change.

Rest of the PR is trigger by formatting changes.

CC: @ednolan @inbal2l @JeffGarland @RaduNichita @mguludag


### **[license.apache_llvm]**

Expand Down Expand Up @@ -131,19 +130,18 @@ Here is snapshot of `default branch` settings in `exemplar` repository:
**Requirement**: There must be a default `Rulesets` configured for any Beman repository (library, infrastructre, documentation, etc.)

Use the following example:

- Go to your repository's settings - e.g., [exemplar/settings](https://github.com/bemanproject/exemplar/settings/).
- Go to `Code and automation` / `Rules` / `Rulesets` - e.g., [exemplar/settings/rulesets](https://github.com/bemanproject/exemplar/settings/rules/).
- You should have a single ruleset named `Default` - e.g., [exemplar/settings/rulesets/beman](https://github.com/bemanproject/exemplar/settings/rulesets/beman).
- Create (via `New ruleset` button) or update (click on `Default` ruleset) it to include the following rules:
- Rulset Name: `Default`
- Enforcement status: `Active`
- Bypass list: Check `Organization admin` and `Repository admin`
- Target branch: Check `Include default branch`
- Go to `Rules` section
- Check `Restrict deletions` and `Block force pushes`
- Check `Require a pull request before merging` and configure it to have `Required approvals: 1`, `Require review from Code Owners` and `Allowed merge methods: Merge, Squash, Rebase`.
- Click `Create` to save the ruleset.
* Go to your repository's settings - e.g., [exemplar/settings](https://github.com/bemanproject/exemplar/settings/).
* Go to `Code and automation` / `Rules` / `Rulesets` - e.g., [exemplar/settings/rulesets](https://github.com/bemanproject/exemplar/settings/rules/).
* You should have a single ruleset named `Default` - e.g., [exemplar/settings/rulesets/beman](https://github.com/bemanproject/exemplar/settings/rulesets/beman).
* Create (via `New ruleset` button) or update (click on `Default` ruleset) it to include the following rules:
* Rulset Name: `Default`
* Enforcement status: `Active`
* Bypass list: Check `Organization admin` and `Repository admin`
* Target branch: Check `Include default branch`
* Go to `Rules` section
* Check `Restrict deletions` and `Block force pushes`
* Check `Require a pull request before merging` and configure it to have `Required approvals: 1`, `Require review from Code Owners` and `Allowed merge methods: Merge, Squash, Rebase`.
* Click `Create` to save the ruleset.

Here is a snapshot of `default branch` settings in `exemplar`:

Expand All @@ -154,8 +152,7 @@ Here is a snapshot of `default branch` settings in `exemplar`:
**Recommendation**: The repository should not use git submodules. Check `cmake.use_find_package` for alternatives.

Known exceptions:

- [mpark/wg21: Framework for Writing C++ Committee Papers](https://github.com/mpark/wg21): A non-C++ submodule designed for drafting ISO C++ papers using LaTeX or Markdown.
* [mpark/wg21: Framework for Writing C++ Committee Papers](https://github.com/mpark/wg21): A non-C++ submodule designed for drafting ISO C++ papers using LaTeX or Markdown.

## Release

Expand All @@ -182,11 +179,11 @@ Known exceptions:
- Build system changes
- Documentation updates

2.4. A "New Contributors" section listing all first-time contributors.
2.4. A "New Contributors" section listing all first-time contributors.

2.5. A "Full Changelog" link to the complete list of commits.
2.5. A "Full Changelog" link to the complete list of commits.

2.6. A "Contributors" section listing all contributors to this release. Note: This section is autogenerated by GitHub Releases!
2.6. A "Contributors" section listing all contributors to this release. Note: This section is autogenerated by GitHub Releases!

Use the following format:

Expand All @@ -201,21 +198,23 @@ Use the following format:

This release has a status of [Under development and not yet ready for production use.](https://github.com/bemanproject/beman/blob/main/docs/beman_library_maturity_model.md#under-development-and-not-yet-ready-for-production-use).


## Changelog

<!-- TODO: Update this section and remove this comment. -->

- <description change> by @${USER} in https://github.com/bemanproject/${REPO}/pull/${PR_ID}
- ...
* <description change> by @${USER} in https://github.com/bemanproject/${REPO}/pull/${PR_ID}
* ...

**Full Changelog**: https://github.com/bemanproject/${REPO}/compare/${PREV_VERSION}...${CURRENT_VERSION}

## New Contributors

<!-- TODO: Update this section and remove this comment. -->

- @${USER} made their first contribution in https://github.com/bemanproject/${REPO}/pull/#${PR_ID}
- ...
* @${USER} made their first contribution in https://github.com/bemanproject/${REPO}/pull/#${PR_ID}
* ...

```

Complete examples can be found in [https://github.com/bemanproject/exemplar/releases](https://github.com/bemanproject/exemplar/releases).
Expand All @@ -224,10 +223,12 @@ Here is a snapshot of notes for a particular release in `exemplar`:

![](./images/release.notes-example01.png)


### **[release.godbolt_trunk_version]**

**Recommendation**: A Beman library should have at least a trunk version deployed on godbolt with nightyclone mode activated. Check [tutorial: Compiler Explorer Deployment](https://github.com/bemanproject/beman/blob/main/guidelines/compiler-explorer-deployment.md).


## Top-level

The top-level of a Beman library repository must consist of `CMakeLists.txt`, `LICENSE`, and `README.md` files.
Expand Down Expand Up @@ -267,7 +268,6 @@ Examples:
**Requirement**: Following the title, the `README.md` must have a one-line badge list. Examples: library status (`[readme.library_status]`), CI status, code coverage, Compiler Explorer example.

Example:

```markdown
![Library Status](https://raw.githubusercontent.com/bemanproject/beman/refs/heads/main/images/badges/beman_badge-beman_library_under_development.svg) ![Continuous Integration Tests](https://github.com/bemanproject/exemplar/actions/workflows/ci_tests.yml/badge.svg) ![Lint Check (pre-commit)](https://github.com/bemanproject/exemplar/actions/workflows/pre-commit.yml/badge.svg) [![Compiler Explorer Example](https://img.shields.io/badge/Try%20it%20on%20Compiler%20Explorer-grey?logo=compilerexplorer&logoColor=67c52a)](https://godbolt.org)
```
Expand Down Expand Up @@ -325,7 +325,7 @@ If the library has been deployed onto Compiler Explorer, add this badge and repl

```markdown
**Implements**: [`std::optional<T&>` (P2988R5)](https://wg21.link/P2988R5) and
[Give **std::optional** Range Support (P3168R1)](https://wg21.link/P3168R1).
[Give *std::optional* Range Support (P3168R1)](https://wg21.link/P3168R1).
```

Note that specifying the revision number is optional.
Expand Down Expand Up @@ -363,7 +363,6 @@ or
**Requirement**: Following the library status line and a new line, the `README.md` must have a `LICENSE` section.

Use exactly the following format:

```markdown
## License

Expand Down Expand Up @@ -420,6 +419,7 @@ find_package(<PackageName> [REQUIRED])

See `[cmake.skip_tests]` in this document for a working example or [exemplar/blob/main/CMakeLists.txt](https://github.com/bemanproject/exemplar/blob/main/CMakeLists.txt).


### **[cmake.project_name]**

**Recommendation**: The CMake project name should be identical to the beman library name.
Expand Down Expand Up @@ -521,6 +521,7 @@ endif()
The `CMakeLists.txt` in the test directory can declare any test-only dependendencies
that are required. For instance:


```CMake
# File: <repo>/tests/CMakeLists.txt
# ...
Expand Down Expand Up @@ -581,7 +582,7 @@ add_subdirectory(beman) # Don't do this
add_subdirectory(optional) # Don't do this
```

### **[cmake.implicit_defaults]**
### **[cmake.implicit_defaults]**

**Recommendation**: Where CMake commands have reasonable default values, and the project does not intend to change those values, the parameters should be left implicitly defaulted rather than enumerated in the command.

Expand Down Expand Up @@ -798,19 +799,19 @@ first possible line in all files which can contain a comment

Examples:

- C++ files shall use the following form:
* C++ files shall use the following form:

```C++
// SPDX-License-Identifier: <SPDX License Expression>
```

- CMake files and scripts shall use the following form:
* CMake files and scripts shall use the following form:

```CMake
# SPDX-License-Identifier: <SPDX License Expression>
```

- Markdown files will use a comment following the title:
* Markdown files will use a comment following the title:

```markdown
# Title
Expand Down
Loading
Loading