Merge branch 'main' into amielpb/wing-logo-blog

blog/2023-05-24-approach-to-devex.md

@@ -0,0 +1,103 @@
+---
+title: Evaluation of Winglang's approach to enhancing DevEx
+description: Evaluation of Winglang's approach for enhancing the Developer Experience (DevEx) of coding cloud applications using principles presented in a cited academic paper.
+authors: shaiber
+tags: [cloud-oriented programming, Winglang, developer experience, DevEx]
+hide_table_of_contents: true
+---
+
+> *"A 2020 [McKinsey study](https://www.mckinsey.com/industries/technology-media-and-telecommunications/our-insights/developer-velocity-how-software-excellence-fuels-business-performance) found that companies with better work environments for their developers achieved revenue growth four to five times greater than that of their competitors."*
+
+This quote is from an insightful [article](https://queue.acm.org/detail.cfm?id=3595878) I recently came across, authored by researchers from DX, the University of Victoria, and Microsoft.
+
+The article delves into the concept of Developer Experience (DevEx) and its profound impact on developer productivity.
+
+As a developer, I am delighted to see that a leading consulting firm is using empirical evidence to demonstrate to companies just how important improving my working conditions can be for them :)
+
+As a co-creator of Winglang, which aims to enhance the DevEx of cloud applications, I am happy to find research-backed validation for what we [intuitively felt](https://docs.winglang.io/blog/2022/11/23/manifesto) when we embarked on our journey: that our success could boost productivity by unlocking the cloud for developers.
+
+However thrilling it is to have my beliefs validated and to see powerful organizations promoting these ideas, that's not the focus of this post.
+
+Instead, I want to focus on another aspect of the paper: its introduction of structured definitions of DevEx and methods for its evaluation.
+
+I believe it's crucial for us, as developers of a language designed to enhance DevEx, to establish a framework for discussing our approach to improving DevEx. This becomes especially vital when our project is open-source, and we aim to involve the community in these discussions.
+
+So, this post will examine Winglang's approach to improving DevEx for cloud apps, through the lens of the structured definitions given in the paper.
+
+This isn't an evaluation of whether we have met our goals. To make that assessment, we'd need to conduct a study involving actual developers using a more mature version of Wing. 
+Instead, it serves as a status check to understand how we are aiming to improve DevEx and how our approaches align with those outlined in the article.
+
+I hope this post will spark your interest, and that you will join us in the subsequent discussion.
+
+<!--truncate-->
+
+## DevEx as defined in the paper
+
+The authors present a framework that condenses the developer experience into three primary dimensions:
+
+1. **Feedback loops:** This term refers to the pace and quality of responses developers receive to their actions. Both feedback from development tools (such as code compilation or tests) and people (like code reviewers) are vital. Swift, concise feedback loops enable developers to finalize their work swiftly with minimal resistance, whereas sluggish feedback loops can lead to delays, exasperation, and disruptions. To enhance DevEx, organizations should aim to expedite feedback loops and optimize both development tools and human hand-off procedures.
+
+2. **Cognitive load:** This concept covers the volume of mental processing required for a developer to execute a task. High cognitive load can stem from complicated tasks, unfamiliar frameworks, having to master too many tools, or inadequately documented code or systems, obstructing developers' capacity to deliver value. To augment DevEx, organizations should strive to decrease cognitive load by eradicating needless obstacles in the development process, creating well-structured code and documentation, and offering user-friendly, self-service tools.
+
+3. **Flow state:** This is a mental zone of immersion in a task, where the individual experiences a sense of energized focus and enjoyment. Encountering a flow state at work can trigger increased productivity, innovation, and personal growth. Interruptions, delays, lack of autonomy, or unclear goals can obstruct a developer's capacity to achieve a flow state. To elevate DevEx, organizations should minimize disruptions, grant developers autonomy, and ensure they have opportunities to engage in fulfilling challenges.
+
+## Evaluating Winglang's DevEx implementation using the paper's parameters
+
+Now that we have the dimensions by which to view DevEx, let's analyze Winglang's efforts according to them. Again, these are Winglang's attributes that are supposed to improve DevEx according to these dimensions. I'm not trying to evaluate whether these attributes do improve DevEx, but rather how they align with the three primary dimensions presented in the academic paper.
+
+### Feedback loops
+Winglang comes with a local simulator and a visualization and debugging console that support instant hot reloading. 
+These tools empower developers to iterate more swiftly with immediate feedback on code modifications, visualizing, interacting, and debugging their code locally via the Wing Console. 
+By minimizing the delay in feedback, developers can promptly rectify errors and enhance their solutions. 
+
+This approach to improving feedback loops aligns with the first dimension identified in the academic paper. 
+It supports more rapid feedback from tools and also from people since the simulator can be used to create fast and cheap to deploy preview environments to be sent for review by other people.
+
+### Cognitive Load
+Winglang aims to lighten developers’ cognitive load by representing abstract cloud resources as native language elements. 
+This strategy diminishes the need for developers to manually control these resources or deeply understand numerous layers of the cloud stack. 
+Instead, they can focus their efforts on crafting application code, while Winglang's compiler handles the cloud mechanics. For example, the automated generation of Identity and Access Management (IAM) policies.
+
+Another key aspect of Winglang's approach to reducing cognitive load is its introduction of [inflights](https://docs.winglang.io/concepts/inflights). They allow developers to write distributed code that looks and feels almost like that of a monolith, with all the cognitive benefits that come with it: code that is easier to follow, test and debug.
+
+Winglang also introduces features such as implicit await for asynchronous calls, further alleviating developers' cognitive burden. 
+
+These cognitive load-reducing attributes seem to align well with the second dimension identified in the academic paper. 
+The challenge is to make sure that the abstractions are not leaky on the one hand and that they don't oversimplify to the degree of diminishing control on the other hand. 
+It's a tough one, and we are not there yet, although I feel like we're on the right path to get there. For example, by supporting import of any Terraform module directly, Wing doesn't restrict developers to using abstractions. There are also many ways to customize and extend Wing, including custom resources and [compiler plugins](https://docs.winglang.io/blog/2023/02/17/plugins) to modify the Terraform output directly.
+
+### Flow State
+Winglang aims to keep developers immersed in their tasks by:
+
+**Providing Autonomy:** Winglang handles cloud mechanics, enabling developers to focus more on the business logic of their applications and less on infrastructure.
+Our goal is to reach a point where they can create entire applications in dev environments without needing much intervention from DevOps.
+On the other hand, Winglang also aims to promote the autonomy of DevOps engineers. [Compiler plugins](https://docs.winglang.io/blog/2023/02/17/plugins) are a way for them to apply non-functional concerns to the application in the form of policies, without having to communicate with the application developers much or to know every resource being used by them.
+
+If we succeed in making developers and DevOps engineers more autonomous, we will be able to reduce the number of context switches and hand-offs between them. This should help induce a flow state in both.
+
+**Minimizing Disruptions:** In Winglang both application and infrastructure code are composed in the same way and use the same programming model and tools. 
+This reduces context switching, whether between languages, tools, or infra and application code. 
+If different developers are handling infra and app code, Winglang reduces the number of context switches associated with communication between them because of the separation of concerns and increased autonomy for both disciplines described above. 
+
+**Fulfilling Challenges:** By abstracting cloud mechanics, developers should be able to focus more on addressing business needs instead of writing glue logic or boilerplate code. This would allow them to grapple with meaningful challenges, keeping them engaged and productive in their flow state. 
+This too is a big challenge, but I feel we're on the right path to make progress there :)
+
+## Conclusion
+It seems like we are attempting to add significant improvements in all three DevEx dimensions coined in the research paper. 
+It is very fulfilling for me to see because it is nice to learn that something you felt intuitively holds against a more formal inspection. 
+
+But attempting something is not enough. 
+While it seems there could be potential in our approach, it is also evident that we face very big challenges. 
+Apart from the obvious one of driving adoption of a new language, I believe our main challenge is our attempt at abstracting the cloud. 
+We need to succeed in making the abstraction non-leaky, or mostly non-leaky, on the one hand, while allowing developers to maintain control when needed on the other hand. 
+Unlike with single machines, this has not been attempted successfully in the cloud yet. 
+I think that the other main area of innovation in Wing, the local simulation, is less challenging to get right, but still not trivial.
+
+In both cases, even if we are successful, it remains to be seen how much of an impact on DevEx Winglang's innovations would make in the real world.
+I can't wait to get to a point in the future when Wing is mature enough and we can make a proper study with real developers to measure the actual impact of our approach on their productivity, creativity and autonomy.
+
+I hope this journey into Wing's approach to improving DevEx of coding cloud apps was enjoyable for you. 
+I'm sure I speak on behalf of everyone on the team when I say that I'd love to get any feedback on our approach in general and our execution of it.
+
+Please check our [docs](https://docs.winglang.io) to learn more or our [playground](https://play.winglang.io) to "experience the experience".
+You are also welcome to [join our Slack](https://t.winglang.io/slack) and our DevEx-related discussions there.

blog/authors.yml

@@ -16,6 +16,12 @@ hasanaburayyan:
   url: https://github.com/hasanaburayyan
   image_url: https://avatars.githubusercontent.com/u/45375125?v=4
   email: [email protected]  
+shaiber:
+  name: Shai Ber
+  title: Co-Founder & COO at Wing Cloud
+  url: https://github.com/ShaiBer
+  image_url: https://avatars.githubusercontent.com/u/1729376?v=4
+  email: [email protected]
 team:
   name: The Wing Team
   url: https://github.com/winglang
@@ -62,4 +68,4 @@ revitalb:
   title: Head of Community
   url: https://github.com/revitalbarletz
   image_url: https://avatars.githubusercontent.com/u/2212620?s=400
-  email: [email protected]
+  email: [email protected]

contributing_versioned_docs/version-latest/01-start-here/01-contributing-to-wing.md

@@ -10,13 +10,13 @@ to know to help out with the Wing project.
 
 There are many ways to contribute to Wing:
 
+* Contributing to the [Wing SDK (standard library)](/contributing/start-here/wingsdk)
 * Reporting bugs through a [GitHub issue](https://github.com/winglang/wing/issues)
 * Writing [documentation and guides](https://github.com/winglang/wing/issues?q=is%3Aissue+is%3Aopen+label%3A%22%F0%9F%93%9A+documentation%22) or adding [examples](/contributing/start-here/docs#%EF%B8%8F-how-do-i-add-an-example)
 * Setting up your [development environment](/contributing/start-here/development) and working on the code
 * Submitting [pull requests](/contributing/start-here/pull_requests) for new features or helping with [reviews](https://github.com/winglang/wing/pulls)
 * Picking up a [good first issue](https://github.com/winglang/wing/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee+sort%3Aupdated-desc+) to work on
 * Reporting and fixing [bugs](/contributing/start-here/bugs)
-* Contributing to the [Wing SDK (standard library)](/contributing/start-here/wingsdk)
 * Find solutions to common issues in our [troubleshooting guide](/contributing/start-here/troubleshooting)
 * Commenting on [RFCs](/contributing/category/rfcs) or submitting one for major features
 * Asking and answering questions in the [Wing Slack](https://t.winglang.io/slack)

contributing_versioned_docs/version-latest/01-start-here/05-development.md

@@ -6,13 +6,23 @@ keywords: [Wing contributors, contributors, workflows]
 
 This topic includes a description of common development workflows for the Wing project.
 
-## Environment Setup
+## How to prepare for take-off? 🐤
 
 :::info
-You can open up this repo just using the badge below. It is recommended to select a 4-core minimum machine.
+You can open up this repo by clicking the badge below. It is recommended to select a 4-core minimum machine.
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/winglang/wing)
 :::
 
+:::info
+For windows we recommend to set the tools up within WSL as some of the scripts 
+don't support windows and expect unix tooling.
+
+Some Guides:
+- [💡 Setup WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install#install-wsl-command)
+- [💡 Setup build essentials for rust](https://stackoverflow.com/questions/52445961/how-do-i-fix-the-rust-error-linker-cc-not-found-for-debian-on-windows-10)
+- [💡 Enable systemd to install docker without the need of Docker Desktop](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/#how-can-you-get-systemd-on-your-machine)
+:::
+
 Here is a list of minimal tools you should install to build the Wing repo in your development
 environment:
 
@@ -35,6 +45,7 @@ cd wing
 pnpm install
 ```
 
+
 :::note Turbo Commands
 [Turbo] commands in this document are structured as
 
@@ -60,7 +71,6 @@ pnpm turbo <task> --filter=<project> -- <args>
 [volta]: https://volta.sh
 [PNPM]: https://pnpm.io
 [Docker]: https://docs.docker.com/get-docker/
-[emscripten]: https://emscripten.org/docs/getting_started/downloads.html
 
 ## Full build
 
@@ -73,6 +83,12 @@ pnpm build
 It will compile, lint, test and package all modules.
 
 ## 🏠 What's the recommended development workflow?
+:::info
+When testing your changes to Wing, locally it may be helpful to be able to easily invoke your local version of the Wing CLI.
+In which case adding a shell alias may be helpful for instance on Linux and Mac you could add: 
+
+`alias mywing=/<PATH_TO_WING_REPO>/apps/wing/bin/wing` to your shell's rc file.
+:::
 
 The `pnpm wing` command can be executed from the root of the repository in order to build and run the
 compiler, SDK (standard library) and the Wing CLI. Turbo is configured to make sure only the changed components are built
@@ -85,11 +101,18 @@ export NODE_OPTIONS=--stack-trace-limit=100
 export RUST_BACKTRACE=full
 ```
 
+Or if you just want to compile your changes and run a local version of the Wing CLI:
+
+```sh
+pnpm compile --filter=winglang
+```
+
+
 Now, you can edit a source file anywhere across the stack and run the compiler with arguments.
 For example:
 
 ```sh
-pnpm wing -- test examples/tests/valid/captures.w
+pnpm wing -- test examples/tests/valid/captures.test.w
 ```
 
 This command runs the full Wing CLI with the given arguments. Turbo will ensure the CLI build is updated.
@@ -120,15 +143,17 @@ If you wish to install it manually, you may do so by running `scripts/setup_wasi
 
 ## 🧪 How do I run tests?
 
-End-to-end tests are hosted under `./tools/hangar`. To get started, first ensure you can [build
+End-to-end tests are hosted under `tools/hangar`. To get started, first ensure you can [build
 wing](#-how-do-i-build-wing).
 
 To run the tests (and update snapshots), run the following command from anywhere in the monorepo:
 
 ```sh
-pnpm turbo test --filter=hangar
+pnpm turbo wing:e2e
 ```
 
+(This is a helpful shortcut for `pnpm turbo test --filter=hangar`)
+
 ### Test Meta-Comments
 
 In your wing files in `examples/tests/valid`, you can add a specially formatted comment to add additional information for hangar.
@@ -153,24 +178,12 @@ This is useful if, for example, the test requires docker. In our CI only linux s
 Benchmark files are located in `examples/tests/valid/benchmarks`. To run the benchmarks, run the following command from anywhere in the monorepo:
 
 ```sh
-pnpm turbo bench
+pnpm turbo wing:bench
 ```
 
-Benchmark files should ideally have a meta-comment with the `cases` key. For example:
-
-```ts
-/*\
-cases:
-  - target: sim
-    maxMeanTime: 900
-  - target: tf-aws
-    maxMeanTime: 1000
-\*/
-```
+(This is a helpful shortcut for `pnpm turbo bench --filter=hangar`)
 
-Given each of these cases, the current purpose is to provide a maxMeanTime (milliseconds) per compilation target.
-If the average time for compiling to this target takes longer than the maxMeanTime, the test will fail.
-Note: In CI, tests likely run much slower than on your local machine, so you may need to observe the CI results to determine the correct maxMeanTime.
+In CI, if these benchmarks regress too far from the current `main` branch, the build will fail.
 
 ## How do I work only on the compiler?
 

contributing_versioned_docs/version-latest/01-start-here/07-wingsdk.md

@@ -10,14 +10,14 @@ This topic includes contribution guidelines related to the Wing SDK, the package
 
 The SDK resides in `libs/wingsdk`. It's written in TypeScript, and is published to npm.
 
+From within the SDK directory you can build it using `pnpm build`. You can also just run the tests with `pnpm test`.
+
 The SDK is built using a couple of extra libraries and tools:
 
 * [CDK for Terraform] ("cdktf") is a framework for defining Terraform infrastructure. The SDK uses it to generate the Terraform files that users deploy.
 * [JSII] is a tool we used to compile the SDK. JSII is a wrapper over TypeScript that makes it possible to use the SDK in other languages like Python, Java, C#, and Go. This is made possible through extra type checks. In practice, the main difference from ordinary TypeScript is that you cannot use advanced TypeScript types like `Partial` or generics in public APIs.
 * [Projen] is a tool used to manage project configuration files. It uses the `.projenrc.ts` file to generate `package.json` and other files. You can modify it and run `pnpm projen` to regenerate the resources. If you are not touching configuration files, you can totally ignore this.
 
-Everything in the SDK can be built by running `pnpm build` from `libs/wingsdk`. You can also run `pnpm test` to just run tests.
-
 In order to work on the source code, you will need to the build at least once so that TypeScript bindings for Terraform resources will be automatically generated.
 These files are not checked in because they are quite large.
 

versioned_docs/version-latest/09-rfcs/2023-03-08-wing-preview-environment.md → contributing_versioned_docs/version-latest/999-rfcs/2023-03-08-wing-preview-environment.md

@@ -1,9 +1,9 @@
 ---
-title: Wing Cloud Preview Environments
+title: "#3696 Wing Cloud Preview Environments"
 description: This document describes an MVP for the first Wing Cloud product - Wing Cloud Preview Environments.
 ---
 
-# #3696 - Wing Cloud Preview Environments
+# Wing Cloud Preview Environments
 
 - **Author(s)**: @ainvoner, @skyrpex
 - **Submission Date**: 2023-08-03