Skip to content

Commit 7e60f91

Browse files
authored
Fb/docs related projects (#37)
* doc structure update * rename related projects to peers * extensibility text v1 * Feature Vector Provider text * feature flags service * minor polish * polish pass for feature flags * add some overview doc parts to README and make a consistency check for future changes
1 parent dbe9278 commit 7e60f91

File tree

9 files changed

+150
-35
lines changed

9 files changed

+150
-35
lines changed

README.md

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,33 @@ SAP BTP feature toggle library enables Node.js applications using the SAP Cloud
1313
npm install --save @cap-js-community/feature-toggle-library
1414
```
1515

16-
## Support, Feedback, Contributing
16+
## Features
1717

18-
This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js-community/feature-toggle-library/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
18+
- Maintain feature toggle states consistently across multiple app instances.
19+
- Feature toggle changes are published from Redis to subscribed app instances with publish/subscribe pattern [PUB/SUB](https://redis.io/topics/pubsub).
20+
- Horizontal app scaling is supported and new app instances will start with the correct state, or fallback values, if they cannot connect to Redis.
21+
- Feature toggle values can be changed specifically for accessors with certain scopes, e.g., for specific tenants, users,...
22+
- Users can register change handler callbacks for specific toggles.
23+
- Users can register custom input validation callbacks for specific toggles.
24+
- Works as a [CDS-plugin](https://cap.cloud.sap/docs/node.js/cds-plugins) and provides a REST service to read and manipulate toggles.
1925

20-
## Code of Conduct
26+
## Peers
2127

22-
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
28+
- [CAP Extensibility Feature Toggles](https://cap-js-community.github.io/feature-toggle-library/peers/#cap-extensibility-feature-toggles)
29+
- [SAP Feature Flags Service](https://cap-js-community.github.io/feature-toggle-library/peers/#sap-feature-flags-service)
2330

2431
## Documentation
2532

2633
Head over to our [Documentation](https://cap-js-community.github.io/feature-toggle-library/) to learn more.
2734

35+
## Support, Feedback, Contributing
36+
37+
This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js-community/feature-toggle-library/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
38+
39+
## Code of Conduct
40+
41+
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
42+
2843
## Licensing
2944

3045
Copyright 2023 SAP SE or an SAP affiliate company and feature-toggle-library contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js-community/feature-toggle-library).

docs/Gemfile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ source "https://rubygems.org"
55
gem "github-pages", "~> 228", group: :jekyll_plugins
66

77
# https://github.com/just-the-docs/just-the-docs/releases
8-
gem "just-the-docs", "~> 0.4.2"
8+
gem "just-the-docs", "~> 0.7.0"

docs/Gemfile.lock

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
11
GEM
22
remote: https://rubygems.org/
33
specs:
4-
activesupport (6.1.7.4)
4+
activesupport (6.1.7.6)
55
concurrent-ruby (~> 1.0, >= 1.0.2)
66
i18n (>= 1.6, < 2)
77
minitest (>= 5.1)
88
tzinfo (~> 2.0)
99
zeitwerk (~> 2.3)
10-
addressable (2.8.4)
10+
addressable (2.8.5)
1111
public_suffix (>= 2.0.2, < 6.0)
12+
base64 (0.2.0)
1213
coffee-script (2.4.1)
1314
coffee-script-source
1415
execjs
1516
coffee-script-source (1.11.1)
1617
colorator (1.1.0)
17-
commonmarker (0.23.9)
18+
commonmarker (0.23.10)
1819
concurrent-ruby (1.2.2)
1920
dnsruby (1.70.0)
2021
simpleidn (~> 0.2.1)
@@ -24,12 +25,13 @@ GEM
2425
ethon (0.16.0)
2526
ffi (>= 1.15.0)
2627
eventmachine (1.2.7)
27-
execjs (2.8.1)
28-
faraday (2.7.9)
28+
execjs (2.9.1)
29+
faraday (2.7.12)
30+
base64
2931
faraday-net_http (>= 2.0, < 3.1)
3032
ruby2_keywords (>= 0.0.4)
3133
faraday-net_http (3.0.2)
32-
ffi (1.15.5)
34+
ffi (1.16.3)
3335
forwardable-extended (2.6.0)
3436
gemoji (3.0.1)
3537
github-pages (228)
@@ -197,8 +199,9 @@ GEM
197199
gemoji (~> 3.0)
198200
html-pipeline (~> 2.2)
199201
jekyll (>= 3.0, < 5.0)
200-
just-the-docs (0.4.2)
202+
just-the-docs (0.7.0)
201203
jekyll (>= 3.8.5)
204+
jekyll-include-cache
202205
jekyll-seo-tag (>= 2.0)
203206
rake (>= 12.3.1)
204207
kramdown (2.3.2)
@@ -210,12 +213,12 @@ GEM
210213
rb-fsevent (~> 0.10, >= 0.10.3)
211214
rb-inotify (~> 0.9, >= 0.9.10)
212215
mercenary (0.3.6)
213-
mini_portile2 (2.8.2)
216+
mini_portile2 (2.8.5)
214217
minima (2.5.1)
215218
jekyll (>= 3.5, < 5.0)
216219
jekyll-feed (~> 0.9)
217220
jekyll-seo-tag (~> 2.1)
218-
minitest (5.18.1)
221+
minitest (5.20.0)
219222
nokogiri (1.13.10)
220223
mini_portile2 (~> 2.8.0)
221224
racc (~> 1.4)
@@ -225,12 +228,12 @@ GEM
225228
pathutil (0.16.2)
226229
forwardable-extended (~> 2.6)
227230
public_suffix (4.0.7)
228-
racc (1.7.1)
229-
rake (13.0.6)
231+
racc (1.7.3)
232+
rake (13.1.0)
230233
rb-fsevent (0.11.2)
231234
rb-inotify (0.10.1)
232235
ffi (~> 1.0)
233-
rexml (3.2.5)
236+
rexml (3.2.6)
234237
rouge (3.26.0)
235238
ruby2_keywords (0.0.5)
236239
rubyzip (2.3.2)
@@ -247,22 +250,22 @@ GEM
247250
unf (~> 0.1.4)
248251
terminal-table (1.8.0)
249252
unicode-display_width (~> 1.1, >= 1.1.1)
250-
typhoeus (1.4.0)
253+
typhoeus (1.4.1)
251254
ethon (>= 0.9.0)
252255
tzinfo (2.0.6)
253256
concurrent-ruby (~> 1.0)
254257
unf (0.1.4)
255258
unf_ext
256-
unf_ext (0.0.8.2)
259+
unf_ext (0.0.9.1)
257260
unicode-display_width (1.8.0)
258-
zeitwerk (2.6.8)
261+
zeitwerk (2.6.12)
259262

260263
PLATFORMS
261264
ruby
262265

263266
DEPENDENCIES
264267
github-pages (~> 228)
265-
just-the-docs (~> 0.4.2)
268+
just-the-docs (~> 0.7.0)
266269

267270
BUNDLED WITH
268271
1.17.2

docs/architecture/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Architecture
4-
nav_order: 4
4+
nav_order: 5
55
---
66

77
<!-- prettier-ignore-start -->

docs/index.md

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,22 @@ npm install --save @cap-js-community/feature-toggle-library
1616

1717
## Features
1818

19-
- maintain feature toggle states consistently across multiple app instances
20-
- feature toggle changes are published from Redis to subscribed app instances with publish/subscribe pattern [PUB/SUB](https://redis.io/topics/pubsub)
21-
- horizontal app scaling is supported and new app instances will start with the correct state, or fallback values, if they cannot connect to Redis
22-
- feature toggle values can be changed specifically for accessors with certain scopes, e.g., for specific tenants, users,...
23-
- users can register change handler callbacks for specific toggles
24-
- users can register custom input validation callbacks for specific toggles
25-
- works as a [cds-plugin](https://cap.cloud.sap/docs/node.js/cds-plugins) and provides a REST service to read and manipulate toggles
19+
- Maintain feature toggle states consistently across multiple app instances.
20+
- Feature toggle changes are published from Redis to subscribed app instances with publish/subscribe pattern [PUB/SUB](https://redis.io/topics/pubsub).
21+
- Horizontal app scaling is supported and new app instances will start with the correct state, or fallback values, if they cannot connect to Redis.
22+
- Feature toggle values can be changed specifically for accessors with certain scopes, e.g., for specific tenants, users,...
23+
- Users can register change handler callbacks for specific toggles.
24+
- Users can register custom input validation callbacks for specific toggles.
25+
- Works as a [CDS-plugin](https://cap.cloud.sap/docs/node.js/cds-plugins) and provides a REST service to read and manipulate toggles.
2626

27-
## Further topics
27+
## Peers
28+
29+
- [CAP Extensibility Feature Toggles](peers/#cap-extensibility-feature-toggles)
30+
- [SAP Feature Flags Service](peers/#sap-feature-flags-service)
31+
32+
## Further Topics
2833

2934
- Configuration and code snippets: [Usage](usage)
30-
- Plugin and REST service for CAP projects: [Plugin and Service](service)
35+
- Plugin and REST service for CAP projects: [Plugin and Service](plugin)
3136
- Architecture and related concepts: [Architecture](architecture)
3237
- Example CAP server: [CAP Example](https://github.com/cap-js-community/feature-toggle-library/blob/main/example-cap-server)

docs/peers/index.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
layout: default
3+
title: Peers
4+
nav_order: 2
5+
---
6+
7+
<!-- prettier-ignore-start -->
8+
# Peers
9+
{: .no_toc }
10+
<!-- prettier-ignore-end -->
11+
12+
<!-- prettier-ignore -->
13+
- TOC
14+
{: toc}
15+
16+
## CAP Extensibility Feature Toggles
17+
18+
Reference documentation:
19+
[https://cap.cloud.sap/docs/guides/extensibility/feature-toggles](https://cap.cloud.sap/docs/guides/extensibility/feature-toggles)
20+
21+
In CAP, the features to be toggled are _pre-built extensions_ of CDS models. These extensions are either active or
22+
inactive, i.e., boolean in nature. They are dynamic in the sense that they can be active for one request and inactive
23+
for another based on the requesting user or tenant. However, their state never changes within the handling of a
24+
request.
25+
26+
Our library supports these types of toggles, by acting as a _Feature Vector Provider_ for CDS, when the library is used
27+
as a CDS-plugin. For details see: [Feature Vector Provider]({{ site.baseurl }}/plugin/#feature-vector-provider).
28+
29+
## SAP Feature Flags Service
30+
31+
Reference documentation:
32+
[https://help.sap.com/docs/feature-flags-service](https://help.sap.com/docs/feature-flags-service)
33+
34+
This SAP BTP service is designed to assist applications with microservice or multi-component architecture in harmonizing
35+
and managing their feature delivery and runtime state. To accomplish this, it provides a service instance with
36+
centralized state that can be queried with a web API or accessed via a dashboard to alter feature states.
37+
38+
We believe this approach works well in practice for many applications. However, our library follows a somewhat different
39+
philosophy for feature toggle management:
40+
41+
- We don't have a dashboard to get an overview of the active feature states in applications with multiple parts.
42+
- We don't have any rollout concepts, like gradual rollout or similar. Our library is client-side, hence decentralized,
43+
and it has no holistic view of how many servers or end-users use it.
44+
- We encourage that the feature configuration is part of the application source code, in human-readable yaml form, in
45+
order to keep the code in sync with the respective features.
46+
- We use redis for state persistence and this allows us to use a sub/pub pattern to keep the local state of many
47+
application instances in sync without polling.
48+
- We focus on input validation and allow flexible, expressive toggle states of different types.
49+
50+
We could imagine supporting the service as an alternative to redis and our source-versioned configuration files at
51+
some point. The service does not come with an associated client library, so there are natural synergies where our
52+
library can help in terms of caching and local state management.
Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Plugin and Service
4-
nav_order: 3
4+
nav_order: 4
55
---
66

77
<!-- prettier-ignore-start -->
@@ -30,6 +30,26 @@ Per default the service endpoints are accessible only to users with the CAP pseu
3030
role preferences, so this setting allows them to set a list of strings, which represent the roles required to access
3131
the service. For details see [@requires](https://cap.cloud.sap/docs/guides/authorization#requires).
3232

33+
## Feature Vector Provider
34+
35+
When used as a CDS-plugin, the library will automatically act as a Feature Vector Provider. This means feature
36+
toggles which match the `<optional-prefix>/fts/<feature-name>` pattern and have a truthy current value at the
37+
start of a request will be passed to CDS on the express request in `req.features`.
38+
39+
In practice, if you have a CDS model extension feature in the directory `/fts/my-feature`, and you configure it inline
40+
or in your config file with:
41+
42+
```yaml
43+
/fts/my-feature:
44+
type: boolean
45+
fallbackValue: false
46+
validations:
47+
- scopes: [user, tenant]
48+
```
49+
50+
then you can control the feature's state, like you would for any other runtime feature, and it will be provided to CDS
51+
and respected for the related requests.
52+
3353
## Service Endpoints
3454
3555
These service endpoints will enable operations teams to understand and modify toggle states. For practical requests,

docs/usage/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Usage
4-
nav_order: 2
4+
nav_order: 3
55
---
66

77
<!-- prettier-ignore-start -->
@@ -120,7 +120,7 @@ anchor, e.g., `module: $CONFIG_DIR/validation.js`.
120120

121121
### For CAP Projects
122122

123-
CAP projects, will use the library as a [cds-plugin](https://cap.cloud.sap/docs/node.js/cds-plugins). Their
123+
CAP projects, will use the library as a [CDS-plugin](https://cap.cloud.sap/docs/node.js/cds-plugins). Their
124124
initialization settings are in `package.json`. For example:
125125

126126
```json
@@ -138,7 +138,7 @@ these settings in place, the `singleton` instance of the library will be initial
138138
after the [bootstrap](https://cap.cloud.sap/cap/docs/node.js/cds-server#bootstrap) event.
139139

140140
{: .info }
141-
Using the feature toggles in CAP projects also enables a [REST service]({{ site.baseurl }}/service/), where toggles can
141+
Using the feature toggles in CAP projects also enables a [REST service]({{ site.baseurl }}/plugin/), where toggles can
142142
be read and manipulated.
143143

144144
### For Non-CAP Projects

test/docs.test.js

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
"use strict";
2+
3+
const { readFileSync } = require("fs");
4+
const { join } = require("path");
5+
6+
describe("docs", () => {
7+
it("documentation README / overview consistency check", async () => {
8+
const headings = ["Install or Upgrade", "Features", "Peers"];
9+
const readmeData = readFileSync(join(__dirname, "..", "README.md")).toString();
10+
const overviewData = readFileSync(join(__dirname, "..", "docs", "index.md")).toString();
11+
for (const heading of headings) {
12+
const extractionRegex = new RegExp(`## ${heading}(.*?)(?:##|$)`, "s");
13+
const readmeContent = extractionRegex
14+
.exec(readmeData)[1]
15+
.replaceAll("https://cap-js-community.github.io/feature-toggle-library/", "");
16+
const overviewContent = extractionRegex.exec(overviewData)[1];
17+
expect(readmeContent).toEqual(overviewContent);
18+
}
19+
});
20+
});

0 commit comments

Comments
 (0)