From 32fb3f13d7f39845377024448f73865d8410ab84 Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Tue, 8 Oct 2024 16:08:39 +0200 Subject: [PATCH 1/5] Create feature-flag-testing.md --- contributor-docs/feature-flag-testing.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 contributor-docs/feature-flag-testing.md diff --git a/contributor-docs/feature-flag-testing.md b/contributor-docs/feature-flag-testing.md new file mode 100644 index 000000000..f230f44d1 --- /dev/null +++ b/contributor-docs/feature-flag-testing.md @@ -0,0 +1,2 @@ +# Testing primitives using a feature flag + From 369d4f634388a154dc473dadc11cd069d9a111d3 Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Tue, 8 Oct 2024 16:29:48 +0200 Subject: [PATCH 2/5] Working on docs --- contributor-docs/feature-flag-testing.md | 37 ++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/contributor-docs/feature-flag-testing.md b/contributor-docs/feature-flag-testing.md index f230f44d1..03d711df6 100644 --- a/contributor-docs/feature-flag-testing.md +++ b/contributor-docs/feature-flag-testing.md @@ -1,2 +1,39 @@ # Testing primitives using a feature flag +## 1. Create a PR +Start by creating a PR in `primer/primitives`. Once all the tests are passing you are ready to move on. + +You will needs the pre-release version later in the process. So copy the version number from the `Published @primer/primitives` job. This is something like `0.0.0-20241007214729`. + +## 2. Create the feature flag +To create the feature flag, you need to log into the [DevPortal](https://devportal.githubapp.com/feature-flags) and navigate to the [feature flags](https://devportal.githubapp.com/feature-flags) section. + +Click on the `New feature flag` button and fill in the required information. + +**Important:** Make sure to choose a descriptive name that is easy to understand. You **CANNOT** change the name. + +Confirm with the `Save feature` button. + +## 3. Add yourself to the feature flag +You should first add yourself to the feature flag and test that everything is working. Afterwards you can add others. + +To do so, open the feature flag and navigate to the `Targeting rules` tab. +Now click the `Switch to another stamp` dropdown and select `ditcom`. +Under `Actors` add yourself. + +## 4. Create a PR in `github/github` +Now it is time to create a PR in `github/github` to add your feature for all users that have the feature flag active. + +This requires a few changes: + +### Install your pre-release +In `github/github` dependencies are installed in workspaces. Primitives are part of the `@npm-workspaces/primer` workspace. +Additionally, since the stable version of primitives is already installed, you need to install your version with an [npm alias](https://docs.npmjs.com/cli/v8/commands/npm-install#:~:text=npm%20install%20%3Calias%3E%40npm%3A%3Cname%3E%3A). + +For example: + +```bash +npm i @primer/primitives-my-feature-flag@npm:@primer/primitives@0.0.0-20241007214729 --workspace=@npm-workspaces/primer +``` + +`bin/generate-service-files.rb ` From 9ac74e98bb8376850106009b17740e0b85d7c5fd Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Wed, 9 Oct 2024 12:56:45 +0200 Subject: [PATCH 3/5] Add instructions for creating a new bundle --- contributor-docs/feature-flag-testing.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/contributor-docs/feature-flag-testing.md b/contributor-docs/feature-flag-testing.md index 03d711df6..f2393bf6d 100644 --- a/contributor-docs/feature-flag-testing.md +++ b/contributor-docs/feature-flag-testing.md @@ -36,4 +36,13 @@ For example: npm i @primer/primitives-my-feature-flag@npm:@primer/primitives@0.0.0-20241007214729 --workspace=@npm-workspaces/primer ``` +### Create a new bundle (optional) +If you want to load some new tokens you can add a new bundle and load it for users who have the feature flags enabled. + +To do so, first create a new bundle by creating a new folder in + +app/assets/stylesheets/bundles/primer-primitives-experimental/index.scss + + + `bin/generate-service-files.rb ` From 4dbcf23538d632f392cf8da6fd580909f1af1539 Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Wed, 9 Oct 2024 13:03:09 +0200 Subject: [PATCH 4/5] Update feature flag testing documentation --- contributor-docs/feature-flag-testing.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/contributor-docs/feature-flag-testing.md b/contributor-docs/feature-flag-testing.md index f2393bf6d..75380fb9d 100644 --- a/contributor-docs/feature-flag-testing.md +++ b/contributor-docs/feature-flag-testing.md @@ -39,9 +39,12 @@ npm i @primer/primitives-my-feature-flag@npm:@primer/primitives@0.0.0-2024100721 ### Create a new bundle (optional) If you want to load some new tokens you can add a new bundle and load it for users who have the feature flags enabled. -To do so, first create a new bundle by creating a new folder in +To do so, first create a new bundle by creating a new folder in `app/assets/stylesheets/bundles/` for example `primer-primitives-your-test`. +In this folder add an `index.scss` file that includes all files you want to load: -app/assets/stylesheets/bundles/primer-primitives-experimental/index.scss +```scss +@import '@primer/primitives-my-feature-flag/dist/css/functional/themes/new-theme.css'; +``` From 8d996875eee2598060d6b227c91c79e51b63f0ee Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Wed, 9 Oct 2024 13:25:15 +0200 Subject: [PATCH 5/5] initial docs on how to create a feature flag --- contributor-docs/feature-flag-testing.md | 39 ++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/contributor-docs/feature-flag-testing.md b/contributor-docs/feature-flag-testing.md index 75380fb9d..ae24039a3 100644 --- a/contributor-docs/feature-flag-testing.md +++ b/contributor-docs/feature-flag-testing.md @@ -1,11 +1,13 @@ # Testing primitives using a feature flag ## 1. Create a PR -Start by creating a PR in `primer/primitives`. Once all the tests are passing you are ready to move on. + +Start by creating a PR in `primer/primitives`. Once all the tests are passing you are ready to move on. You will needs the pre-release version later in the process. So copy the version number from the `Published @primer/primitives` job. This is something like `0.0.0-20241007214729`. ## 2. Create the feature flag + To create the feature flag, you need to log into the [DevPortal](https://devportal.githubapp.com/feature-flags) and navigate to the [feature flags](https://devportal.githubapp.com/feature-flags) section. Click on the `New feature flag` button and fill in the required information. @@ -15,6 +17,7 @@ Click on the `New feature flag` button and fill in the required information. Confirm with the `Save feature` button. ## 3. Add yourself to the feature flag + You should first add yourself to the feature flag and test that everything is working. Afterwards you can add others. To do so, open the feature flag and navigate to the `Targeting rules` tab. @@ -22,11 +25,21 @@ Now click the `Switch to another stamp` dropdown and select `ditcom`. Under `Actors` add yourself. ## 4. Create a PR in `github/github` + Now it is time to create a PR in `github/github` to add your feature for all users that have the feature flag active. This requires a few changes: +### Preload the feature flag + +You need to add your feature flag to `app/controllers/application_controller/preload_feature_flags_dependency.rb`: + +``` +:primitives_my_feature_flag # a comment describing what the feature flag does +``` + ### Install your pre-release + In `github/github` dependencies are installed in workspaces. Primitives are part of the `@npm-workspaces/primer` workspace. Additionally, since the stable version of primitives is already installed, you need to install your version with an [npm alias](https://docs.npmjs.com/cli/v8/commands/npm-install#:~:text=npm%20install%20%3Calias%3E%40npm%3A%3Cname%3E%3A). @@ -36,16 +49,36 @@ For example: npm i @primer/primitives-my-feature-flag@npm:@primer/primitives@0.0.0-20241007214729 --workspace=@npm-workspaces/primer ``` +**NOTE:** This package needs to be checked into git. On dotcom all packages are added in git. + ### Create a new bundle (optional) + If you want to load some new tokens you can add a new bundle and load it for users who have the feature flags enabled. -To do so, first create a new bundle by creating a new folder in `app/assets/stylesheets/bundles/` for example `primer-primitives-your-test`. +To do so, first create a new bundle by creating a new folder in `app/assets/stylesheets/bundles/` for example `primer-primitives-your-bundle`. In this folder add an `index.scss` file that includes all files you want to load: ```scss @import '@primer/primitives-my-feature-flag/dist/css/functional/themes/new-theme.css'; ``` +You now need to load your css bundle if the feature flag is active by placing the code below in all nessesary places, for example `app/views/layouts/application.html.erb`. + +```ruby +# this bundle (index.scss in the folder) will only be loaded if the users has the primitives_my_feature_flag feature flag enabled +<%= stylesheet_bundle "primer-primitives-your-bundle" if user_feature_enabled?(:primitives_my_feature_flag) %> +``` + +Now you need to generate the `SERVICEOWNERS` and `CODEOWNERS` by running `bin/generate-service-files.rb` in the console or by running it as a task in vs code. + +It should add a line like this to the `SERVICEOWNERS`: +``` +app/assets/stylesheets/bundles/primer-primitives-your-bundle/ :primer_dotcom +``` + +And a line like this to the `CODEOWNERS`: -`bin/generate-service-files.rb ` +``` +/app/assets/stylesheets/bundles/primer-primitives-your-bundle/ @github/primer-reviewers +```