From c01ae4260e273fa96b8075a8715021a9eba4031f Mon Sep 17 00:00:00 2001 From: Daniel Ramos Date: Mon, 29 Jul 2024 10:33:40 -0700 Subject: [PATCH 1/3] Documentation improvements --- README.md | 82 +++++++++++++++++++++++++++++++++++++++-- site/src/pages/index.js | 1 - 2 files changed, 79 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5fcb1d594..1ccb0d821 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,92 @@ -# Piranha +# PolyglotPiranha [![Join the chat at https://gitter.im/uber/piranha](https://badges.gitter.im/uber/piranha.svg)](https://gitter.im/uber/piranha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +PolyglotPiranha is a lightweight code transformation toolset for automating large scale changes. At Uber, it is mostly used to clean up stale feature flags. + + +## Installation + +To install Polyglot Piranha, you can use it as a Python library or as a command-line tool. + +### Python API + +To install the Python API, run the following command: + +```bash +pip install polyglot-piranha +``` + +### Command-line Interface + +To install the command-line interface, follow these steps: + +1. Install [Rust](https://www.rust-lang.org/tools/install) +2. Clone the repository: `git clone https://github.com/uber/piranha.git` +3. Navigate to the cloned directory: `cd piranha` +4. Build the project: `cargo build --release` (or `cargo build --release --no-default-features` for macOS) +5. The binary will be generated under `target/release` + +## Example Usage + +```python +from polyglot_piranha import execute_piranha, PiranhaArguments, Rule, RuleGraph, OutgoingEdges + +# Original code snippet +code = """ +if (obj.isLocEnabled() || x > 0) { + // do something +} else { + // do something else! +} +""" + +# Define the rule to replace the method call +r1 = Rule( + name="replace_method", + query="cs :[x].isLocEnabled()", # cs indicates we are using concrete syntax + replace_node="*", + replace="true", + is_seed_rule=True +) + +# Define the edges for the rule graph. +# In this case, boolean_literal_cleanup is already defined for java [see src/cleanup_rules] +edge = OutgoingEdges("replace_method", to=["boolean_literal_cleanup"], scope="parent") + +# Create Piranha arguments +piranha_arguments = PiranhaArguments( + code_snippet=code, + language="java", + rule_graph=RuleGraph(rules=[r1], edges=[edge]) +) + +# Execute Piranha and print the transformed code +piranha_summary = execute_piranha(piranha_arguments) +print(piranha_summary[0].content) +``` + +For additional examples, please visit our [demo page](https://uber.github.io/piranha/docs/reference/getting-started/demos) + +## Documentation + +Find more examples and explanations of the toolset on the [documentation webpage](https://uber.github.io/piranha/) or in the +[POLYGLOT_README.md](POLYGLOT_README.md) file + + +## Feature Flags + + Feature flags are commonly used to enable gradual rollout or experiment with new features. In a few cases, even after the purpose of the flag is accomplished, the code pertaining to the feature flag is not removed. We refer to such flags as stale flags. The presence of code pertaining to stale flags can have the following drawbacks: - Unnecessary code clutter increases the overall complexity w.r.t maintenance resulting in reduced developer productivity - The flags can interfere with other experimental flags (e.g., due to nesting under a flag that is always false) - Presence of unused code in the source as well as the binary - Stale flags can also cause bugs -Piranha is a tool to automatically refactor code related to stale flags. At a higher level, the input to the tool is the name of the flag and the expected behavior, after specifying a list of APIs related to flags in a properties file. Piranha will use these inputs to automatically refactor the code according to the expected behavior. +PolyglotPiranha is a tool that can automatically refactor code related to stale flags. At a higher level, the input to the tool is the name of the flag and the expected behavior, after specifying a list of APIs related to flags in a properties file. Piranha will use these inputs to automatically refactor the code according to the expected behavior. -This repository contains four independent versions of Piranha, one for each of the four supported languages: Java, JavaScript, Objective-C and Swift. **It also contains a redesigned variant of Piranha (as of May 2022) that is a common refactoring tool to support multiple languages and feature flag APIs. If interested in this polyglot variant, goto [Polyglot Piranha](POLYGLOT_README.md)**. +PolyglotPiranha (as of May 2022) is a common refactoring tool to support multiple languages and feature flag APIs. +This repository also contains four legacy language-specific implementations Piranha, for Java, JavaScript, Objective-C, and Swift, before it was redesigned in May 2022. To use/build each version, look under the corresponding [lang]/ directory and follow instructions in the corresponding [lang]/README.md file. Make sure to cd into that directory to build any related code following the instructions in the README. diff --git a/site/src/pages/index.js b/site/src/pages/index.js index d3bed1f5f..b69a345ce 100644 --- a/site/src/pages/index.js +++ b/site/src/pages/index.js @@ -41,7 +41,6 @@ export default function Home() {
-
); From b36dadd5a0a17c405b9440ed42182b943cd56cdd Mon Sep 17 00:00:00 2001 From: Daniel Ramos Date: Tue, 30 Jul 2024 09:17:22 -0700 Subject: [PATCH 2/3] Update README.md --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1ccb0d821..4dd6e8060 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # PolyglotPiranha -[![Join the chat at https://gitter.im/uber/piranha](https://badges.gitter.im/uber/piranha.svg)](https://gitter.im/uber/piranha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - PolyglotPiranha is a lightweight code transformation toolset for automating large scale changes. At Uber, it is mostly used to clean up stale feature flags. @@ -66,12 +64,11 @@ piranha_summary = execute_piranha(piranha_arguments) print(piranha_summary[0].content) ``` -For additional examples, please visit our [demo page](https://uber.github.io/piranha/docs/reference/getting-started/demos) +For additional examples, please visit our [demo page](POLYGLOT_README.md#getting-started-with-demos) ## Documentation -Find more examples and explanations of the toolset on the [documentation webpage](https://uber.github.io/piranha/) or in the -[POLYGLOT_README.md](POLYGLOT_README.md) file +Find more examples and explanations of the toolset in the [POLYGLOT_README.md](POLYGLOT_README.md) file ## Feature Flags From 5341a2abf57b6482ab93c4eca51edae081c86de1 Mon Sep 17 00:00:00 2001 From: Daniel Ramos Date: Tue, 30 Jul 2024 09:58:33 -0700 Subject: [PATCH 3/3] Update README.md --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 4dd6e8060..92bd8c897 100644 --- a/README.md +++ b/README.md @@ -64,11 +64,10 @@ piranha_summary = execute_piranha(piranha_arguments) print(piranha_summary[0].content) ``` -For additional examples, please visit our [demo page](POLYGLOT_README.md#getting-started-with-demos) ## Documentation -Find more examples and explanations of the toolset in the [POLYGLOT_README.md](POLYGLOT_README.md) file +For more examples and explanations of the toolset, please check our demos and extended [POLYGLOT_README.md](POLYGLOT_README.md) file. ## Feature Flags