Skip to content
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.

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

docs(feature-flags): create concrete documentation #594

Merged
merged 44 commits into from
Aug 10, 2021
Merged

docs(feature-flags): create concrete documentation #594

merged 44 commits into from
Aug 10, 2021

Conversation

am29d
Copy link
Contributor

@am29d am29d commented Aug 6, 2021

Issue #, if available: aws-powertools/powertools-lambda#23

Description of changes:

Added documentation on feature flags.

Checklist

Breaking change checklist

RFC issue #:

  • Migration process documented
  • Implement warnings (if it can live side by side)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

@pull-request-size pull-request-size bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 6, 2021
@codecov-commenter
Copy link

codecov-commenter commented Aug 6, 2021

Codecov Report

Merging #594 (802aab3) into develop (7b3b032) will not change coverage.
The diff coverage is 100.00%.

Impacted file tree graph

@@           Coverage Diff            @@
##           develop     #594   +/-   ##
========================================
  Coverage    99.95%   99.95%           
========================================
  Files          113      113           
  Lines         4535     4535           
  Branches       245      245           
========================================
  Hits          4533     4533           
  Partials         2        2           
Impacted Files Coverage Δ
...owertools/utilities/feature_flags/feature_flags.py 100.00% <ø> (ø)
...da_powertools/utilities/feature_flags/appconfig.py 100.00% <100.00%> (ø)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7b3b032...802aab3. Read the comment docs.

@boring-cyborg boring-cyborg bot added the documentation Improvements or additions to documentation label Aug 6, 2021

**Dynamic feature flags** are typically used for experiments where you'd want to enable a feature for a limited set of customers, for example A/B testing and Canary releases. These are better suited for this utility, as you can create multiple conditions on whether a feature flag should be `True` or `False`.
**Dynamic feature flags** are typically used for experiments where you'd want to enable a feature for a limited set of
Copy link
Contributor

Choose a reason for hiding this comment

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

i dont think this is accurate. you can achieve the same thing with static flags. The dynamic part just allows you to change them faster without redeploying your service.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Even if we can redploy fast (enough), without rules the flags will have the same value in our code execution, it doesn't make them dynamic. I think we can't achieve dyamic behaivour, say A/B testing, by just redeploying static flags.


!!! tip "Read [this article](https://martinfowler.com/articles/feature-toggles.html){target="_blank"} for more details on different types of feature flags and trade-offs"
!!! tip "Read [this article](https://martinfowler.com/articles/feature-toggles.html){target="_blank"} for more details
Copy link
Contributor

Choose a reason for hiding this comment

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

would appreciate a link to my original feature flags blog, but no pressure ;)
https://isenberg-ran.medium.com/aws-lambda-feature-toggles-made-simple-580b0c444233

Copy link
Contributor

Choose a reason for hiding this comment

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

Also a pretty good article https://www.atlassian.com/continuous-delivery/principles/feature-flags

Although Martin Fowler's blog is very comprehensive.

Copy link
Contributor

Choose a reason for hiding this comment

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

CloudBees have their own implementaiton: https://www.cloudbees.com/blog/ultimate-feature-flag-guide

Copy link
Contributor Author

Choose a reason for hiding this comment

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

ha! I have stumbled upon all of the mentioned articles by now 😅, we can make a list

docs/utilities/feature_flags.md Outdated Show resolved Hide resolved
}
```

In this example the feature flag is **static**, which mean it will be evaluated without any additional context such as
Copy link
Contributor

Choose a reason for hiding this comment

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

i think global would be the better term. that's what i was going to say at the webinar too

Copy link
Contributor

Choose a reason for hiding this comment

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

static is accurate when referencing a programming language. Something that constantly returns the same value regardless of the context.

docs/utilities/feature_flags.md Outdated Show resolved Hide resolved
docs/utilities/feature_flags.md Outdated Show resolved Hide resolved
@heitorlessa
Copy link
Contributor

heitorlessa commented Aug 6, 2021 via email

@pull-request-size pull-request-size bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Aug 10, 2021
@heitorlessa
Copy link
Contributor

New terminology section

image

@boring-cyborg boring-cyborg bot added the tests label Aug 10, 2021
@ran-isenberg
Copy link
Contributor

Screen Shot 2021-08-10 at 15 49 15

You can use this flow image @heitorlessa

@michaelbrewer
Copy link
Contributor

Screen Shot 2021-08-10 at 15 49 15

You can use this flow image @heitorlessa

The source file would be cool. In figma or which ever tool the cool kids are using today ;)

=== "CDK"

```typescript hl_lines="2-7 13-32 34-35 40 47 54"
import * as cdk from '@aws-cdk/core';
Copy link
Contributor

Choose a reason for hiding this comment

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

@heitorlessa - i know this might seem be silly, but let's do the CDK example in python too.

@heitorlessa
Copy link
Contributor

heitorlessa commented Aug 10, 2021 via email

* develop:
  chore: only build docs on docs path
  refactor(feature-flags): add debug for all features evaluation" (#590)
  chore: enable autolabel based on PR title
  chore(deps-dev): bump pdoc3 from 0.9.2 to 0.10.0 (#584)
…tools-python into docs/feature-toggle-examples

* 'develop' of https://github.com/awslabs/aws-lambda-powertools-python:
  chore(deps): bump boto3 from 1.18.15 to 1.18.17 (#597)
  feat(feature flags): Add not_in action and rename contains to in (#589)
  chore(deps-dev): bump mkdocs-material from 7.2.2 to 7.2.3 (#596)
  chore(deps): bump boto3 from 1.18.1 to 1.18.15 (#591)
  chore(deps): bump codecov/codecov-action from 2.0.1 to 2.0.2 (#558)
  fix(deps): bump poetry to latest (#592)
  chore(deps-dev): bump mkdocs-material from 7.2.1 to 7.2.2 (#582)
@heitorlessa
Copy link
Contributor

As discussed with @risenberg-cyberark, the last part of doc review found an accidental bug - Multiple conditions are not being evaluated as an logic AND.

I'll finalize docs as-is and start prepping the release mechanics in parallel

@heitorlessa heitorlessa added this to the 1.19.0 milestone Aug 10, 2021
@heitorlessa
Copy link
Contributor

MERGING - Thank you so much everyone @am29d @risenberg-cyberark @michaelbrewer @pcolazurdo.

@heitorlessa heitorlessa marked this pull request as ready for review August 10, 2021 18:32
@heitorlessa
Copy link
Contributor

I'll keep the CDK sample in Typescript as-is instead of fixing for Python... we can do this later.

@heitorlessa heitorlessa changed the title docs(feature-flags): add examples to documentation docs(feature-flags): create concrete documentation Aug 10, 2021
@heitorlessa heitorlessa merged commit b9a1d54 into aws-powertools:develop Aug 10, 2021
@michaelbrewer
Copy link
Contributor

michaelbrewer commented Aug 10, 2021

I'll keep the CDK sample in Typescript as-is instead of fixing for Python... we can do this later.

I will take a crack at it, but low priority and not a blocker for release.

@ran-isenberg
Copy link
Contributor

@michaelbrewer i have a working python cdk version, will add it here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. tests
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants