Forem: Mercedes-Benz.io

GitHub Copilot in Frontend Development

Helmuth Saatkamp — Wed, 31 Jan 2024 09:06:06 +0000

In modern aviation, there are machines capable of flying themselves, but we don't trust them because we know it's not a question of "if" they fail, but "when" and "how". Therefore, by having a pilot and a copilot to operate it, we are provided with the guarantee of safety we need to use it.

When comparing an Airplane with Artificial Intelligence (AI), there are some similarities: A Machine capable of operating on its own that requires an external factor (a human) to provide the initial inputs and ensure things are working as expected.

Advanced AI has taken the world by storm. And, like Pandora's box, it's not something that can be undone, but learn from it and adapt. To benefit from this change, you first need to understand how it works and what this new tool is capable of. Below, you will find some insights and examples of how you can use an AI and fly with it during Frontend development.

Define a Context
Break Down the Problem
Define an Outcome
Prompt Examples
Conclusion

For this purpose, the examples are based on the GitHub Copilot Chat, but it should work similarly to any other AI tool.

1. Define a Context

For effective use of the AI, provide context, especially with a new project. Treat interactions as a conversation, breaking down the problem and discussing solutions, akin to pair programming. Start with a broad goal before diving into details.

For example, when building a calculator with Vue, you could write a comment like this.

/*
Create a calculator component with the following features:
- use Vue 3 composition API
- use TypeScript
- Show results as I type
- Support all basic math operations
*/

GitHub Copilot can quickly generate the base code for the new component.

2. Break Down the Problem

Communicate your main goal and the steps to achieve it. Breaking down the process helps it be understood better. Let it generate code after each step instead of all at once.

Continuing with the calculator example, you could now add the Numpad and their styles as a next step.

create a numpad with basic operators in html using tailwind, the buttons should be squared, rounded and with the gray color

3. Define an Outcome

Learning from examples benefits both humans and AI pair programmers. For example, we might want to extract names from an array and store them in a new array. By giving examples, we can help GitHub Copilot understand our intent.

/* 
Map through an array of objects
Example: Extract names from the data array
Desired outcome: ['Harry', 'James', 'Potter']
 */

4. Prompt Examples

Here are some prompt examples of how to interact with it and give you ideas to create your own.

As a rule of thumb: Always validates the content/code generated by an AI. It is not perfect and can generate things that do not make sense (Hallucinates) or do not work.

Prototyping

The AI code generation accelerates prototyping, allows quick design iterations, early problem detection, and boosts team collaboration.

Create a Method

Create a function that does something.

create a function to sort product by name

Create a Regex

Regex can be hard to write, but the AI can help you with that.

create a regex to validate email address

Convert X to Y

You can use the following example to convert a JSON object to Typescript, or even another language like Swift, C# or Python.

convert the following json to typescript and order properties alphabetically
{
  id: 1,
  name: 'John Doe',
  birthday: '1990-01-01',
  city: 'Berlin,
  country: 'Germany'
}

Or transform a value into something else. For example, convert a hex color to its equivalent RGBA.

equivalent rgba color for #ff0033

Code Refactoring

The AI can help you optimize your code by suggesting better ways to do things.

improve the function_name function

Or get some suggestions on how to refactor a method into smaller ones.

make the function_name function smaller by splitting it into smaller chunks

Debugging

The AI can identify software issues by scrutinizing code patterns, logs, or anomalies that could lead to bugs.

Explain a Method

explain the function_name function

Code Insight

Where is the error in the function dateRange when executing it with the following parameters: '2022-01-01', '2022-12-31', { interval: 'ME' }

Documentation

The AI can analyze code and related resources to automatically generate concise, contextual documentation for developers.

Document a Method

generate documentation for the function function_name

Testing

The AI can automate testing creation and help you quickly analyze code, identify potential vulnerabilities, and simulate various test scenarios.

Create Test

Create a unit test for a method.

create unit test for the function_name function

or for a component.

create unit test for the component_name.vue component

Add Test Cases

You can also add test cases to an existing test.

test function_name function against undefined, null, empty string or numbers.

Learning

The AI can help you learn new things by providing you with documentation and examples.

How To

You can ask for documentation on how to use a method, or even set a context such as I'm learning javascript and I'm going to ask questions about the language and its built-in methods, and then processed and type only Array.reduce().

how to use the Array.reduce() method in javascript

Is it also possible to clarify a topic.

What is the difference between "for of" and "for in" in javascript

4. Conclusion

AI tools like GitHub Copilot can significantly enhance the process of software development. By defining a context, breaking down the problem, defining an outcome, and using the correct prompts, developers can effectively communicate with the AI to improve their development experience. However, it's crucial to remember that AI is not infallible. Always validate the generated content and code to ensure it meets your requirements and expectations. As we continue to adapt and learn from these advanced AI tools, they will become an increasingly integral part of our development workflows, acting as a reliable copilot in our coding journey.

What are your thoughts on AI? How do you use it? Let us know in the comments below!

Improving Your Development Documentation Project (2 of 3)

Javier Hernández — Fri, 03 Mar 2023 11:35:34 +0000

What this article covers

Basic guideline to design a survey to get feedback from your documentation users.

Tools

MS Forms.

Introduction

Now that we know the current status of our documentation better (See Part 1), it is time to talk about our users. Why? Because we have created the documentation for them to be able to use our products, platforms or tools.

But what do we know about our users' needs? Who are they? We may all have assumptions about them. But in fact, we know nothing most of the time.

A user survey is a good method to discover how our users perceive and use our docs, to know their current needs and to decide what to improve first.

Read the following steps to know how to prepare your user survey.

Step 1 - Design a User Survey

To design a user survey we need to know what to ask. But language is tricky so even if we are technical writers, we should double-check the survey's questions with another colleague (and a UX designer, if possible).

About the following questions take them as reference to create your own survey:

In which team/product do you work?
What is your role?
How (un)familiar are you with the Write your documentation name here documentation?
How often do you read the Write your documentation name here documentation?

Never.

From time to time.

A few times a month.

Monthly.

Weekly.

I don't even close that tab.

Which topics do you need to find in the Write your documentation name here?
Which topics would like to find in the Write your documentation name here?
How (un)satisfied are you with the Write your documentation name here documentation?

Very unsatisfied.

Unsatisfied.

Neutral.

Satisfied.

Very satisfied.

Please explain briefly why you are (un)satisfied with the Write your documentation name here documentation.
How (un)useful do you find the Write your documentation name here documentation?

Not useful at all.

Not useful.

Neutral.

Useful.

Very useful.

Explain briefly why you consider the Write your documentation name here documentation (un)useful.
Do you bookmark the Write your documentation name here pages you need?

Never.

I only bookmark the topics I need.

I bookmark Write your documentation name here main topics only.

I bookmark the Write your documentation name here home page only.

Always.

Please let us know to what extent the following statements apply to you personally:

When I need to find some information on a page, I make CTRL+F:

Never.

Rarely.

Sometimes.

Often.

Always.

When I need to find some information on the [Write your documentation name here] pages, I scroll:

Never.

Rarely.

Sometimes.

Often.

Always.

How often do you use the Write your documentation name here page Search box:

Never.

Rarely.

Sometimes.

Often.

Always.

Regarding the content of a page, what do you prefer?

A plain content structure - No tabs, no accordions. All the information is shown at once.

A plain content structure containing some visual elements and disclosing content progressively.

If you were to make one suggestion for improving the Write your documentation name here pages, what would it be?

Better visual design.

Content should be more comprehensible.

Content should be easier to find.

Others (Develop your answer).

Acknowledgement: Thanks to Daniela Diener and Roksana Skryzcka for reviewing the initial survey.

Why These Questions?

Design your questions according to the topic you want feedback about for example: user browsing behavior, page layout preferences, missing topics, etc.

To know which type of feedback we are addressing with the sample survey of this page, read the following table:

Type of Feedback	Question Number	Explanation
Your users (role, team/product)	1, 2	Knowing the role, team or product of our users, helps us to identify: Our audience. Which role/teams are reading our docs the most This information can lead us to develop role or team/product focused documentation, or address specific issues or lack of interest impacting the documentation.
Awareness by role, and team/product	3, 4	If our platform, toolset, product or project has a lot of people using it, checking the awareness level is a must to double check that our people know where to find the documentation they need, and what we have prepared for them.
Frequency of use	3	Answers to this question will tell us if our documentation is being used and how much. Knowing this, we can take further actions to deepen the engagement, or reinforce it if the docs are not being checked frequently.
Topics of interest	4	Too many times we create the docs that we think would be of use for our users. This question will tell us if we are right, and which topics need to be revamped (or removed).
Level of (dis)satisfaction	5, 6	A satisfied user is another word for useful docs (and product!). A low level of satisfaction gives us the chance to ask Why?, and find the source of that dissatisfaction.
Usefulness perception	7, 8	We can think that our documentation is useful but, again, our users will either confirm it or deny it.
Access point to our documentation	9	Sometimes we think that our users access directly our documentation typing the URL in the browser. This question will tell us about the bookmarking habits of our users bookmark. With that in mind, we will have a better idea of the impacts of changing any page or section name that could probably be bookmarked. Here, an effective and reliable communication strategy for changes is key.
Browsing and search behavior	10, 11	Browsing and search behavior have a decisive impact on how we will design our pages, and which visual elements can be used. For example, using collapsible elements may cause troubles to CTRL+F users that, for example, work with Chrome.
Reading behavior	10, 11, 12	Same as previous topic.
Direct Improvements	13, 14	This is the open-air gold mine. Users will tell you what they want and see as a positive impact for the docs.

MS Forms

Use any survey creation tool that fits your needs. I used MS Forms because it was available and provided an easy way to:

Visualize the number of participants.
Provide different kinds of diagrams to visualize the results of the questions.
Download the results in a consumable Excel format.
Easily share the survey.

Step 2 - Schedule the Survey

Scheduling the survey at the right time is as important as the survey itself. We are all focused on providing value to our projects and don't want to get distracted.

So check in advance with the required roles (POs normally), the best date and time to run the survey.

If your users are not your teammates, Customer Support or an equivalent department may be the ones to seek.

When discussing the time for the survey, remember to:

Share the objectives of the survey.
Set the time available to complete the survey.
Explain the importance and benefits of their collaboration.
Ask them to request all team members to attend the meeting.
Try to not interrupt their workflow.

Tip: For agile product development teams, including the survey during the daily or retrospective meeting seems the right time.

Step 3 - Survey Time

During the survey meeting remember to introduce yourself and:

Present the documentation improvement project: What, Why and How.
Explain the importance of improving the docs.
Explain the structure of the survey.
Release the survey!

To Be Continued…

What's Next?

The next article will analyze the results of the survey, and identify the most important ones.

API Testing with Java and Spring Boot Test - Part 2: Improving the solution

Luiz Eduardo Martins — Tue, 07 Feb 2023 08:06:43 +0000

In the last part of this step-by-step, we created the project, set up the test framework and also did all the configurations needed to run our API tests.

You can see the first part of the series here:

API Testing with Java and Spring Boot Test - Part 1: The basic setup.

Let's continue to grow our test framework, but first, we need to do some improvements to the existing code. In this guide, we'll:

Refactor the object mapping (to be easier to handle with the JSON files)
Improve the response validations
Handle multiple environments inside our tests.

These changes will let our code base cleaner and easier to maintain while helping us to create a scalable framework of API tests.

Let's do it.

Refactoring the Object mapping

We'll take advantage of using the Spring boot Repository to separate the responsibility of mapping the objects (JSON) we're going to use inside our tests. That way, we can do another step forward in our code cleanup.

So, first of all, we're going to:

Create a new package called repositories
Then we create a new Class inside this package called FileUtils.

We'll also take the opportunity to change the way we map the object to not be hard-coded but be in a proper resource file. That way when we need to change the test data, we don't have to change the test but only the correspondent resource file.

As you can see in the file above, we created a function to read a JSON file and then return the object already mapped - similar to the approach we had before in the test file.

Now, we'll structure the resources folder to accommodate the JSON files.

In the resources folder, let's create a new directory called user and then create a file to store the request body of the operation we'll do.

After that, we need to update our test. Now we want to get the file data by using the new function we created for that purpose.

The updated test will look like that:

Much better! By keeping the code cleaner, we are helping our future selves with its maintenance - trust me, you'll be very glad to see this.

Improving the response validation

Great! Now, let's have a look at the response validation.

In some cases, we want to check the full response body - or at least some parts of it - to fulfill the test requirements.

To do that, we'll create:

A new Repository to abstract the responsibility and help us check the full JSON response body
A function to handle the check of the JSON response.

We'll also add the "jsonassert" dependency to assert the JSON.

The pom.xml file will look like that:

The newly created ResponseUtils class will be something like this:

The next step should be to use this new function and improve our test. To do that, we'll configure a GET request on YourApiService and return the full Response object. Then we should be able to check the response body.

public Response getRequest(String endpoint) {

    return RestAssured.given(spec)
        .contentType(ContentType.JSON)
    .when()
        .get(endpoint);
}

Now, it's just a matter of adding the test case to the ApiTest test class and using the same strategy of letting the JSON response file be in its proper directory. Finally, we'll have something like this:

@Test
public void testGetUser() throws IOException, JSONException {

    Response res = yourApiService.getRequest("/users/2");

    JsonNode expectedResponse = FileUtils.readJsonFromFile("responses/user/specific.json");

    assertThat(res.statusCode(), is(equalTo(200)));
    ResponseUtils.assertJson(res, expectedResponse);
}

Quite easy to understand if you just look at the test case :)

Executing the tests over multiple environments

Now we have the tests properly set, and everything is in the right place. One thing that could be in your mind right now is: "Ok, but I have a scenario in my product in which I need to run my test suit over multiple environments. How do I do that?".

And the answer is - property files.

The property files are used to store specific data which we can use along our test suit, like the application host, port, and path to the API. You can also store environment variables to use within your test framework. However, be careful since we don't want to make this information public. You can see an example in the lines below.

With Spring boot, we take advantage of using the "profiles" to set the specifics of the environments our application has, and make them available as Spring boot profiles.

So, let's do that. Inside the resources folder, we'll create a new file called application-prod.properties to store the values of the production cluster of the test application. The file will store something like this:

apitest.base.uri=https://reqres.in
apitest.base.path=/api
apitest.token=${TOKEN}

Now, the only thing missing is to change our service to get the values stored in the property file.

To get the values from the property files, we'll use the annotation @Value. This annotation will provide the values from the properties we set in the application-prod.properties file.

*Bear in mind: * You'll need to set the environment variable before using it here. The @Value annotation will grab this value from the environment variables you have set.

The updated version of YourApiService class will look like this:

That's a great step up. This way, if you have multiple environments in your setup, you just need to create another application-YOUR_PROFILE_NAME.properties.

Executing the test suit

You must be wondering: How do I run the test suit with this newly created profile?

The answer is simple, just execute mvn clean test -Dspring.profiles.active=prod.

By default, if you just run the mvn clean test command, Spring Boot will try to find a file called application.properties and automatically activate it.

Now we have significantly improved the test setup of our application by:

The refactoring of the Object mapping to clean up our code and apply some best practices
Improving the response validation by adding a new dependency and using it to simplify the check
Learning how to handle multiple test environments. This should be useful when it comes to companies that have layers of environments before the code reach production

Are you curious about the article? Building a Java API test framework part 3 will further improve our application. We will then go deeper into the following topics:

Test reporting with Allure reports
Configure a CI pipeline with GitHub actions
Publish the test report on GitHub pages

See you soon!

Improving Your Development Documentation Project (1 of 3)

Javier Hernández — Wed, 18 Jan 2023 17:10:20 +0000

What this article covers

First steps on how to improve an existing documentation project.

Tools

Confluence, GitHub web and desktop version, and MarkdownPad2.

Introduction

Developer Documentation is a curated set of files describing all the active workflows, setups, tools, conventions, best practices, and How-tos of your software development product. Through this article, I will refer to it as "documentation" or "docs".

Documentation supports your team members in their daily and future developments. It also helps new joiners to reach cruise speed during the onboarding period. But to do so, your documentation must be up-to-date and well-structured.

Keeping the docs up-to-date and in good shape requires resources and dedicated time. Yet often our project time or budget constraints prevent us from taking care of our docs properly.

This series of articles aims to serve as a documentation improvement guide.

Know Your Ground

Step 1 - Organize Your Improvement Project

Developer documentation has to be visible to increase the chances of success, and to find collaborators (to improve it). To do so, you need a space to visualize your project, describe it, and track your progress.

Use your teams/company collaboration tool for that purpose. For this article, we'll be using Confluence.

Space Structure

The structure of an improvement project may differ from one project to another. Take the following space structure as a reference that you can adapt to your needs (then iterate!):

Space Name	Page Name	Child Page	Description
[Your Documentation Project´s Name]			Name of your documentation project.
	Overview		Explain briefly the What, Why and How of the documentation.
	Dashboard		Centralized page to easily access all project pages.
	Analysis		Media and results of documentation analysis.
	Roadmap		Visualization of the estimated dates to implement each improvement.
	Improvement Project	Communication Grid	Contact person by topic.
		Improvement Plan	Implementation phases and items.
		Coordination Meetings	Grid to align with your manager or collaborators (Optional).

Once your improvement project space is set up, you are ready to:

Present it to all your team members, including Product Owners and Scrum Masters.
Track and show your progress.
Visualize documentation issues/blocking points.
Access all your project resources.

Tip: Explain how documentation issues negatively impact teams´ performance. It will help Product Owners and Scrum Masters to understand and provide your project with the resources you need.

Step 2 - Identify Your Documentation Issues

Identifying your documentation issues means spotting all the types of issues living among your docs. Some documentation issues are:

Grammar, spelling and syntax errors.
Confusing/Not logical page structure.
Unclear/Verbose text.

In the following table, you can learn a little more about the main documentation issues:

Documentation Issue	Example	Fix strategy
Grammar, spelling, syntax	Bad gramar, speling and sintax distraks reders from what yo´r tring to say. It alsso give the idea that you doesnt know about it.	Use a text checker to support your writing. Some good options are Grammarly, Hemingway or QuillBot.
Page structure	Coming soon!	Review your page structure. It shows the logical flow of the information contained according to the objective of the page, for example: Introduction, Prerequisites, First Step, Working with.../Available Features.
Naming	Coming soon!	Define a naming strategy for page titles, sections and subsections.
Page elements	Coming soon!	Standardize the use of the following elements: lists, tables, tabs, notes, collapsible elements and images.
Text unclear or too verbose	Verbose text: Selecting this method means the content that is currently in the Awesome server caches is never served. The next time the edge server receives a request for the content, it retrieves the latest version from your origin server. Not verbose: Using this method prevents the content of the Awesome server cache to be served. Therefore, the Awesome server will retrieve the latest version from your origin server for every new request on the content.	Be concise.
Random text formatting	This is file.name with bold format. It is OK. But if I also use a different format for a `file.name` (the same content element), it is more difficult for users to identify what they need and the type of information we are providing.	Standardize the use of bold and italics for files, folder names, code snippets and code elements (functions, objects, methods, parameters, API names, etc.).
Too many topics on a single page	A Getting Started page must provide the information and steps required for user to get started. An About this Chapter page must provide introduce the topic, give a context, talk about features briefly.An API reference page (or pages) must focus on those references, not providing getting started information. In other words, 1 page, 1 topic.	Stick to "One topic per page".
Unnecessary screenshots	Coming soon!	Use screenshots or images ONLY when strictly necessary. If you can explain it briefly, do not use screenshots.
Type of notes	Coming soon!	Standardize each type of use case for notes (Info, Help, Warning, etc.).

Now we can start to target and record the issues of our documentation.

The following table will help you to perform that task:

Nav Option	Page	Section	Subsection	Issue	Link
Add nav. option name	Page number	Section name	Subsection name	Issue name

Depending on the size and complexity of your documentation, targeting these basic issues may take a while.

Take the chance and join me on the journey to better documentation and improve your documentation project now.

To Be Continued…

What`s Next?

In the next article, we will describe how to run a user survey to gather useful feedback from your users/readers. This invaluable feedback will help us prioritize the documentation issues to fix first.

API Testing with Java and Spring Boot Test - Part 1: The basic setup

Luiz Eduardo Martins — Fri, 16 Dec 2022 14:12:08 +0000

At Mercedes-benz.io (MB.io), we collaborate as multiple multi-disciplinary teams (nothing new to a Scrum-based organization).

I'm part of one of those teams, responsible for a Java-based microservice. Since this microservice sends data to a back-office application, we need to test the APIs provided by it.

With that said, we had the challenge to build a new API test framework from scratch.

In this series of articles we'll show:

How we choose the tools
The process of creating and improving the test framework
Pipeline configuration
Test report

Choosing the language and framework

The main reason why we went for a Java-based framework is that the background of our team is Java and the microservice itself is written in this language. Our team is composed of Java developers, so they can contribute to building the right solution for our team and also maintain the code base of the test repository in case it's needed.

The test framework we've chosen to be the base of our solution was Rest Assured.io. The reason behind it is that rest assured is already used in several projects within our tribe at MB.io and is also widely used and maintained in the community.

We also added Spring Boot to organize, structure and be the foundation of the project.

Setting up the project

Step 1: Create the project

We choose Maven as our dependencies manager. Now, the first thing to do is to add the dependencies we need in our project.

Tip: You can use the spring boot initializer to get the basic pom.xml file with the spring initial setup.

After the initial setup, we need to add the dependencies for the rest-assured test framework and other things we'll use to make our lives easier.

The pom.xml file should be something like that:

With this, we should be able to start organizing our project.

Step 2: Changing the `Main` class

The Main class should be changed to a SpringBootApplication. And the main method must be configured to run as a SpringApplication.

Step 3: Create a `Service` to manage your API

To abstract access and configure the requests in one single place, we can create a new Service and take advantage of it.

Here is the place to set the proper configuration of the requests.

Let's create a new method here to abstract the use of a post request. In this post request, we'll provide the URL and the JSON body as parameters, so the file will be something like this:

Note: We'll return the full response to be able to validate what we want within the test itself.

As you can see in the file above, we also take advantage of the built-in RequestSpecification that Rest-assured has to set the baseURI and basePath for this service. This is a smart way to configure your service because if you have more than one service in our test framework, each of them can have its setup and host.

Step 4: Add a test case

First things first, let's add the proper annotations to be a spring boot JUnit 5 test class.

@ExtendWith(SpringExtension.class)
@SpringBootTest
@TestInstance(TestInstance.Lifecycle.PER_CLASS)

After that, let's add a constructor method and assign the Service to be used in our test as a class variable.

private final YourApiService yourApiService;

public ApiTest(YourApiService yourApiService) {

    this.yourApiService = yourApiService;
}

Now we are good to start adding the test cases here. Let's do that.

The postRequest method expects two parameters:

the endpoint we want to send the data as a String;
the request body as a JsonNode.

The first thing we want to do is create an object to send in the request body of our request. We'll take advantage of the jackson-databind library to help us with the object mapping.

@Test
public void testCreateUser() throws JsonProcessingException {

    ObjectMapper mapper = new ObjectMapper();

    String body = "{\"name\": \"Luiz Eduardo\", \"job\": \"Senior QA Engineer\"}";
    JsonNode requestBody = mapper.readTree(body);
}

Now, we need to make the request and validate what we want. Let's add that to our test case. The final results should be something like that:

Note: Bear in mind that this is just the first iteration, we'll improve the code to keep the responsibilities within the respective classes.

What we've seen so far:

The project's basic setup
How to structure the project
How to abstract the requests in the service layer
The first functional test case

This is the end of part 1 of this series of articles. The next part will cover:

A short refactor on the object mapping
Improve the response validation
Property files

See you soon!

Automated Frontend Workflow

Helmuth Saatkamp — Fri, 16 Dec 2022 00:09:34 +0000

In a world where robots have not yet taken our place, we still have to deal with repetitive tasks. We are constantly trying to find the easiest and laziest way to accomplish something, some people call it efficiency. By letting the machine do the tedious part, it could give us more time to work or spend on interesting stuff.

An automated frontend workflow is a set of processes and tools that are used to manage and streamline the development of a website or application. This typically involves tasks such as code linting (e.g. Prettier, ESLint), building, testing (e.g. Jest), and deployment, and is designed to make it easier for developers to work on the front end without having to worry about these details. Automated frontend workflows can be created using a variety of tools, such as build tools (e.g. Webpack, Vite), and continuous integration platforms (e.g. Jenkins, GitHub Actions).

In short, automation for software development means reducing complexity to something that anyone could use and understand.

In this article, you will learn how to create, add and automate common frontend tools within your workflow.

If you are interested in learning about some of these tools you can check my other article about Testing in JavaScript

Project
1. Setup
2. Prettier
3. Sass
4. TypeScript
5. Vite
6. Vitest
7. VitePress
8. Storybook
9. ESLint
10. StyleLint
Git
1. Git setup
2. Git hooks
  1. Lefthook
GitHub Actions
1. Code Analysis
2. Linters
3. Testing
4. Branch Protection
5. Docs
Conclusion

Project

The goal is to build a modern monorepo project using the following stack:

Vue: An approachable, performant, and versatile framework for building web user interfaces.
Sass: CSS with superpowers.
TypeScript: A strongly typed programming language that builds on JavaScript.
Vite: Fast bundler to create web projects
Vitest: A Vite-native fast unit test framework.
VitePress: Modern SSG framework built on top of Vite.
Storybook: Storybook is a frontend workshop for building UI components and pages in isolation.
Prettier: An opinionated code formatter.
ESLint: Statically analyzes your code to quickly find problems.
Stylelint: A modern linter that helps you avoid errors and enforce conventions in your styles.

Most steps can be manually adjusted to your preferred JS library or framework, like React, Svelte or Angular. You can check the final result at the following link: https://github.com/helmuthdu/automated-frontend-workflow

Setup

To start, let's create a new project. Open the terminal, create a new folder and initialize the project.

mkdir automated-frontend-workflow
cd automated-frontend-workflow
npm init

After completion. Open the newly created package.json file and add the workspaces config to set it as a monorepo.

...
"workspaces": [
  "packages/*"
]

A monorepo is a single repository that contains multiple projects. The main reason for it is to streamline work within a dev team that maintains multiple apps using shared pieces of code, for example, a User Interface library.

Next, you have to install and configure the common tools which will be used during the development.

Prettier

Install Prettier:

npm i -D prettier

Create a .prettierrc file.

{
  "arrowParens": "avoid",
  "bracketSameLine": true,
  "bracketSpacing": true,
  "htmlWhitespaceSensitivity": "ignore",
  "printWidth": 120,
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "none",
  "useTabs": false,
  "vueIndentScriptAndStyle": false
}

You can find more information about these options in the official documentation.

Sass

Install Sass:

npm i -D sass

TypeScript

Install TypeScript:

npm i -D typescript

Create a tsconfig.json file.

{
  "compilerOptions": {
    "target": "ESNext",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "jsx": "preserve",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "lib": ["ESNext", "DOM"],
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["vitest/globals"]
  },
  "ts-node": {
    "compilerOptions": {
      "module": "ESNext"
    }
  }
}

Vite

Install Vite:

npm i -D vite @vitejs/plugin-vue vue vue-tsc

Create a vite.config.ts file.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()]
});

Vitest

Install Vitest:

npm i -D vitest jsdom @vue/test-utils

Create a vitest.config.ts file.

/// <reference types="vitest" />

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
  test: {
    globals: true,
    environment: 'jsdom'
  }
});

Update the scripts in the package.json file by adding a new command:

"scripts": {
  ...
  "test": "vitest",
},

VitePress

Install VitePress:

npm i -D vitepress

Create a docs/.vitepress/config.ts file.

export default {
  title: 'Automated Frontend Workflow',
  description: 'Frontend Tooling made Easy',
  base: 'https://helmuthdu.github.io/automated-frontend-workflow/'
};

The base property should reflect your git project.

Create a docs/index.md file.

# Hello VitePress

[Go to Storybook](https://helmuthdu.github.io/automated-frontend-workflow/storybook)

Update the scripts in the package.json file by adding these new commands:

"scripts": {
  ...
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs",
  "docs:preview": "vitepress preview docs"
},

Storybook

Install Storybook:

npx sb init --builder @storybook/builder-vite

Open the .storybook/.main.js file and configure it as follows.

module.exports = {
  stories: ['../packages/**/*.stories.mdx', '../packages/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: '@storybook/vue3',
  core: {
    builder: '@storybook/builder-vite'
  },
  features: {
    storyStoreV7: true
  },
  async viteFinal(config, options) {
    config.base = './';
    return config;
  },
  env: config => ({
    ...config,
    STORYBOOK_BASE_URL:
      process.env.NODE_ENV === 'production' ? 'https://helmuthdu.github.io/automated-frontend-workflow/storybook/' : ''
  })
};

The STORYBOOK_BASE_URL property should reflect your git project.

Create a .storybook/manager-head.html file.

<!-- .storybook/manager-head.html -->
<base href="%STORYBOOK_BASE_URL%" target="_blank" />
<meta name="description" content="Components for my awesome project" key="desc" />

Update the package.json file to output the build result to the docs/public/storybook folder, this will be important to deploy our docs and the storybook on the same GitHub page.

"scripts": {
   ...
   "storybook": "start-storybook -p 6006",
   "storybook:build": "build-storybook -o docs/public/storybook"
},

ESLint

Install ESLint with Prettier, TypeScript and Vue support, and add a package to output the result as sarif format which will be used later for the GitHub integration.

npm i -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser @microsoft/eslint-formatter-sarif eslint-config-prettier eslint-plugin-prettier eslint-plugin-vue vue-eslint-parser @vue/eslint-config-typescript

Create a .eslintrc.cjs file.

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  parser: '@typescript-eslint/parser',
  parserOptions: {
    parser: '@typescript-eslint/parser',
    ecmaVersion: 2021
  },
  plugins: ['@typescript-eslint', 'prettier'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended',
    'plugin:storybook/recommended'
  ],
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    '@typescript-eslint/no-unused-vars': [
      'off',
      {
        argsIgnorePattern: '^_'
      }
    ],
    'prettier/prettier': 'error'
  },
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      rules: {
        // The core 'no-unused-vars' rules (in the eslint:recommeded ruleset)
        // does not work with type definitions
        'no-unused-vars': 'off'
      }
    },
    {
      files: ['**/__tests__/*.{j,t}s?(x)', 'packages/**/src/**/*.spec.{j,t}s?(x)'],
      env: {
        jest: true
      }
    },
    {
      files: ['packages/**/src/**/*.vue'],
      parser: 'vue-eslint-parser',
      parserOptions: {
        extraFileExtensions: ['.vue'],
        ecmaFeatures: {
          jsx: true
        },
        ecmaVersion: 2021
      },
      extends: ['plugin:vue/vue3-recommended', '@vue/typescript/recommended', 'plugin:prettier/recommended']
    }
  ]
};

Update the scripts in the package.json file by adding these new commands:

"scripts": {
  ...
  "lint": "npm run lint -ws",
  "lint:report": "eslint --ext .jsx,.js,.ts,.tsx,.vue --fix --format @microsoft/eslint-formatter-sarif --output-file eslint-results.sarif packages/**/src",
},

Stylelint

Install Stylelint along with the standard configs, Prettier, Sass, and Vue support.

npm i -D postcss postcss-html stylelint stylelint-config-prettier stylelint-config-recommended-vue stylelint-config-standard-scss

Create a .stylelintrc file extending these configs. It is included an optional rule to check if the CSS selector follows the BEM Name Convention.

{
  "extends": ["stylelint-config-standard-scss", "stylelint-config-recommended-vue/scss", "stylelint-config-prettier"],
  "rules": {
    "selector-class-pattern": [
      "^.([a-z0-9-]+)?(__([a-z0-9]+-?)+)?(--([a-z0-9]+-?)+){0,2}$",
      { "resolveNestedSelectors": true }
    ]
  }
}

Git

Git is a distributed version control system for tracking changes in files and can be used for collaboratively developing source code during software development.

Git setup

Create a new repository in GitHub, open the terminal inside the project, initialize git, add a commit and a remote, then push the changes.

git init
git add README.md
git commit -m "feat: project setup"
git branch -M main
git remote add origin https://github.com/$GITHUB_USER/$REPO_NAME.git
git push -u origin main

Replace the $GITHUB_USER and the $REPO_NAME variables with your GitHub user and repository name.

Git hooks

Git has a way to fire off custom scripts when certain actions occur, such as commit and push. There is a variety of hooks available, but you can start with these:

commit-msg: Check the commit message format or spelling errors.
pre-commit: Check for errors and enforce project coding standards.
pre-push: Run tests to ensure working software

You can create them manually, or use Lefthook to simplify the process.

Lefthook

Lefthook is a fast and powerful Git hooks manager for Node.js and any other type of project written in Go.

To install, open the terminal in your project:

npm install -D lefthook

After installation, it will generate a lefthook.yml file which can be customized to perform a static code analysis before committing the code. For example, it can ensure that the git commit follows the git-conventional-commits, and use Prettier, ESLint, and Stylelint to check, format, and fix any file which will be committed and run any test related with Vitest depending on the filetype and run each in parallel.

For .html, .json, and .yml files, reformat with Prettier
For .css and .scss files, check the styles with Stylelint and Prettier after.
For .js and .ts files, excluding tests, run ESLint and check related tests with Vitest after.
For .spec.js and .spec.ts tests files, run ESLint, and the tests with Vitest after.

To start, initialize the git-conventional-commits by running the npx git-conventional-commits init command, and then update the lefthook.yml as follows:

commit-msg:
  commands:
    validate:
      run: >
        npx git-conventional-commits commit-msg-hook {1}

pre-commit:
  parallel: true
  commands:
    lint:misc:
      glob: '*.{html,json,yml}'
      run: npx prettier --write {staged_files}
    lint:css:
      glob: '*.{css,scss}'
      run: >
        npx stylelint --fix {staged_files} &&
        npx prettier --write {staged_files}
    lint:js:
      glob: '*[!.{spec,test}].{[tj]s,[tj]sx}'
      run: >
        npx eslint --fix {staged_files} && 
        npx vitest related {staged_files} --passWithNoTests --run --environment jsdom
    test:unit:
      glob: '*.{spec,test}.{[tj]s,[tj]sx}'
      run: >
        npx eslint --fix {staged_files} &&
        npx vitest {staged_files} --run --environment jsdom

That's it, now every time you commit your code these commands will run automatically

GitHub Actions

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.

The GitHub Actions workflows are located in the .github/workflows folder and are composed of:

Workflow: A workflow is a configurable-automated process that will run one or more jobs.
Events: An event is a specific activity in a repository that triggers a workflow run.
Jobs: A job is a set of steps in a workflow that executes on the same runner. Each step is either a shell script that will be executed or an action that will be run.
Runners: A runner is a server that runs your workflows when they're triggered. Each runner can run a single job at a time.
Actions: An action is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task.

Do not worry, you will understand better those processes with the examples below showing common cases.

Code Analysis

To ensure code quality, the code should be checked, tested, and reported.

Start by creating a new file in your GitHub repository called .github/workflows/code-analysis.yml. This file will define the workflow that your GitHub Action will follow.
In the .github/workflows/code-analysis.yml file, you can use the on keyword to specify when the workflow should be triggered. For example, you might want to trigger the workflow when a new code is pushed to the repository with the option to trigger it manually. You can do this by adding the following lines to the file:

   on:
     push:
       branches:
         - 'main'
     # set this property to enable manual trigger option in GitHub
     workflow_dispatch:

You can set the concurrency property to run only one instance, so if it is running while a new commit is pushed it will be canceled and restarted. You can use the contexts to define a proper key.

   # github.workflow context to determine the current workflow name
   # github.ref context to determine the current branch name
   concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}
     cancel-in-progress: true

Furthermore, it is required to set some permissions to read and write content. You can check all available permissions by clicking here.

   permissions:
     # required for all workflows
     security-events: write
     # only required for workflows in private repositories
     actions: read
     contents: read

Actions can be cached to accelerate the process. For example, in the Node.js setup action, it is possible to cache the NPM packages, so it won't have to fetch everything every time the job is running.

   - name: Setup Node.js
     uses: actions/setup-node@v3
     with:
       node-version: 16
       cache: 'npm'

To complete, in the job section, specify the steps that the GitHub Action should perform. For example, you might want to first check out the code from the repository, generate a code analysis report and upload it to GitHub:

   # code-scanning.yml
   name: Code scanning

   on:
     push:
       branches:
         - 'main'
     workflow_dispatch:

   concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}
     cancel-in-progress: true

   jobs:
     eslint:
       name: Eslint
       runs-on: ubuntu-latest
       permissions:
         # required for all workflows
         security-events: write
         # only required for workflows in private repositories
         actions: read
         contents: read
       steps:
         - name: Checkout Repository
           uses: actions/checkout@v3

         - name: Setup Node.js
           uses: actions/setup-node@v3
           with:
             node-version: 16
             cache: 'npm'

         - name: Install dependencies
           run: npm ci

         - name: Run linter
           run: npm run lint:report
           continue-on-error: true

         - name: Upload analysis results to GitHub
           uses: github/codeql-action/upload-sarif@v2
           with:
             sarif_file: eslint-results.sarif
             wait-for-processing: true

After creating the workflow, you can go to your GitHub repo and run it manually to check the results. You can trigger this action by clicking in the Actions Tab -> Code scanning Workflow -> Run workflow Dropdown -> Run workflow Button.

To see the result, go to the Security -> Code scanning section.

The missing part is that these checks should also run on any code which will be submitted through a PR in the project and block any change which does not follow the required rules.

Linters

Linters, in short, are tools to help you improve your code. It can be configured to run on every Pull Request (PR) to guarantee that any new code has the same standards defined.

Similar to the previous workflow, start by creating a new file in your GitHub repository called .github/workflows/linter.yml.
In the on keyword, set it to run on pull_request.

   on: [pull_request]

Configure the concurrency to have only one workflow running at a time.

   # github.workflow context to determine the current workflow name
   # github.ref context to determine the current branch name
   concurrency: ${{ github.workflow }}-${{ github.ref }}

Define the Runner. Usually, the ubuntu-latest runner is a safe choice.

   jobs:
     eslint:
       runs-on: ubuntu-latest

Additionally, add all steps to perform a checkout action to fetch the code, do another action to setup-node with the node-version 16 with the cache enabled for all npm packages, install all dependencies with npm ci command and finally run the linters with npm run linter command

# linter.yml
name: Linter

on: [pull_request]

# github.workflow context to determine the current workflow name
# github.ref context to determine the current branch name
concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  eslint:
    name: Eslint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

Testing

It should run similarly to the Linters workflow but executing the npm run test command instead.

# testing.yml
name: Testing

on: [pull_request]

# github.workflow context to determine the current workflow name
# github.ref context to determine the current branch name
concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  vitest:
    name: Vitest
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test

Branch Protection

Adding the workflows is just one step, you also need to configure the branch rules. Open your repository in GitHub and go to Settings -> Branches.

Click in the Add rule button, insert the repo name your want this rule to be associated with at the beginning, and make sure the workflows are set as required in the Require branches to be up to date before merging option.

To complete, click on the Create button at the bottom of the page.

Docs

For the documentation, we have a scenario where there is VitePress and Storybook need to publish together. Before creating the workflow, enable the pages in the repo settings.

Similar to the previous workflow, start by creating a new file in your GitHub repository called .github/workflows/docs.yml.
In the on keyword, set it to run on push to the main branch, also add the option to trigger it manually with workflow_dispatch.

   on:
     # Runs on pushes targeting the default branch
     push:
       branches:
         - 'main'
     # Allows you to run this workflow manually from the Actions tab
     workflow_dispatch:

Define the Runner to the ubuntu-latest.

   jobs:
     eslint:
       runs-on: ubuntu-latest

Add all actions to perform a checkout to fetch the code, do another action to setup-node, install all dependencies with the npm ci command, build storybook with the target to the public folder inside the docs, so when VitePress runs the build command it will copy the storybook files together and after everything is built trigger an action to setup GitHub Pages and update generated page artifact.
To complete, add another job, grant the permissions to write, and call the deployment action.

# docs.yml
name: Docs

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - 'main'
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  build:
    name: Build
    # Specify runner + deployment step
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build Storybook
        run: npm run storybook:build

      - name: Build VitePress
        run: npm run docs:build

      - name: Setup pages
        uses: actions/configure-pages@v2

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'docs/.vitepress/dist'

  deploy:
    name: Deploy
    # Add a dependency to the build job
    needs: build
    # Specify runner + deployment step
    runs-on: ubuntu-latest
    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source
    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Conclusion

The tooling used as part of the frontend development process ensures everything is working or is done as expected, and automation is designed to make it easier for developers to work without having to worry about these details.

This is just the tip of the iceberg, to learn more, check the GitHub Actions documentation and take a look at some starter workflows.

ARTICLE WRITING: Feedback and how we integrated it with a developer

chief3000 — Thu, 25 Aug 2022 15:12:00 +0000

Nice that you have found the way to the third part of my article series on the topic of writing. For me, this is an exciting subject because I can learn a lot about how to put my thoughts on paper. At the same time, it is fulfilling to motivate others to join me on this journey. The first part was primarily about the benefits I have experienced myself, that arise from writing articles. This was followed by part two, which focused on how to get a structured start to writing. Where I describe what steps you go through when writing and point out tools to keep your motivation high and improve your writing style.

The importance of feedback and its influence on your writing

This article is about feedback because I have noticed how it helps me to improve and how important it is to think about routines and processes to motivate yourself.
Make yourself available for feedback that you would like to have on your work. At the same time, it's essential to me to offer to write together and give each other feedback. Writing together is simply more fun.

Feedback

This is about the importance of feedback in the writing process and what influence it can have on one's own writing.

The main benefits I see in choosing to solicit feedback from others are:

Engagement
Collaboration
Inspiration
Learning

To get feedback, you need to have produced something, so you also need an initial commitment and the will to write something yourself. Feedback is beneficial when writing an article so that you don't just work isolated on your topic but open up to others and incorporate their perspective, ideas, and opinions. You can be inspired by your feedback givers, stimulate yourself with it, and integrate new thoughts and link them. You may even get a fresh look at a topic you are stuck on or having trouble putting into words. You can learn from the experiences of others who have been in similar situations or are more experienced in writing down their thoughts.

Types of feedback

Depending on what stage of the writing process you are at, feedback has different purposes.
Initially, when you are still in the research or outline phase, it can help you to sharpen the goal of your article and what you want to achieve with it. You can check if what you plan to write is technically correct.
During the writing process, you can get ideas on storytelling and feedback on whether you have expressed yourself clearly. You can exchange ideas on how to bind the reader to your text and keep it exciting.
Towards the end, it's more a matter of textual corrections and formulations or even a content-related approval.

Guidelines regarding Feedback

What is also essential to me, is to define in advance how to give feedback correctly. It isn't always that simple. Different personalities react differently, and with a generally accepted guideline, you define the common ground of understanding. In the best case, the guidelines are created and accepted together upfront. Then each participant feels understood and can include his or her expectations.

Giving feedback the right way

Giving feedback is not a one-way street, if you help each other with your articles there are also some things to consider from the perspective of the feedback provider. One of the main points is honesty. It doesn't help anyone if you only find euphemistic words and thus only confirm the writer in his work. Instead, it is more important to look deeper, to identify possible misunderstandings and structural problems.

General advice to improve the added value and readability of the article is relevant. An open approach to mistakes is crucial. Talk about the mistakes openly and honestly. Constructive feedback is essential. Not only noticing mistakes but also offering hints, advice and possible improvements are part of it.

It is necessary as a feedback provider that the work on the article is the subject of the feedback and not the criticism of the author. As said in the beginning, in the best case, you agree in advance with those giving feedback on this open behavior.

Prepare yourself for the feedback

On the other hand, as the person asking for feedback, you should also be mentally prepared for possible criticism and be open to it. It is also helpful if you develop the courage to express that you are dissatisfied with a certain passage of the article as a writer and communicate this to the feedback provider. It is needed to actively set the right mindset for learning from your mistakes. As a writer, you are often very emotionally attached to your written work. It can then feel harsher than intended when you are criticized for your work. Don't take it personally. The intention of the feedback is to improve the article, and you should always keep that in mind on both sides.

Receiving feedback and how to deal with it.

Stay calm and open to feedback about your article. Your feedback provider has the best intentions in mind. Think about who you are getting feedback from. What focus has the person in mind with his or her suggestions? Choose your feedback providers carefully. Differentiate between those who can help you with your content and those who can improve your writing. Make this clear when requesting feedback from them. Just pick the comments that make you reflect and improve your work from your perspective. Ask clarifying questions about the feedback to help you better understand what was said.

Articles are written language, therefore seek verbal exchange on crucial comments. Then uncertainties will be clarified most easily. Don't be caught off guard by the amount of feedback you get, it's normal. Embrace the rich feedback because it gives you many opportunities to reflect on your work and see it from a different angle. Writing is an art form and everyone interprets it differently. It's normal for opinions to drift apart during the feedback process and you don't always have to agree.

The Mercedes-Benz.io way for feedback and collective writing

GIT our Feedback tool

We think it's helpful to get feedback not just from one person, but from different people with different backgrounds and experiences. It is supportive to have a process you know very well and that you can easily follow. As developers, we are very familiar with the principle of pull requests. Which we use to get feedback on the code we write before we put it back into the main code. Even as a non-developer this process is easy to use. You can do the same with your articles.

We have a Git repository at Mercedes-Benz.io where any writing enthusiast can create a feature branch for their article. When ready for feedback, the author then simply submits a pull request to gather feedback from the writing group. If you want to get extra early feedback on your not-quite-finished article, you can also mark it as a draft. The reviewers will then give timely suggestions on the article, following the pull request etiquette. Then it is only a few small steps to the publication on our company blog. This process has proven to be better than sending documents back and forth.

Mob writing

You probably know the principle of pair programming. If you want to know anything else about it, read this article by Hannes, where he goes into detail. In a nutshell, two developers work on code together to support each other in finding the best technical solution. If you want to push the collaboration level even further, you can do it in a group in so-called mob programming. We do something similar at Mercedes-Benz.io only with writing articles.

We do this to motivate each other, get early feedback and inspiration and support each other. Another plus point is that you have another moment where you can network with other writers. We are all in the same boat because we are not full-time writers. That's why the group is quite homogeneous and everyone is ready to take in the feedback of the others. This was born out of the will to deal with writing articles regularly. Spending at least 30 minutes a week writing your article will help develop routines.

Therefore, those who are currently working on an article meet on Friday for about 45 minutes in a joint meeting.

The first minutes are used to briefly introduce what everyone wants to work on in the following part of the session.
Then everyone writes for 30 minutes without disruption while listening to relaxing music that promotes creativity.
After that, there is an optional chance to read out your result and get some feedback.

I always find it amazing how much can be created in a few minutes and how great the pride is when you have once again created a successful paragraph. Feedback from these sessions is more of a spontaneous reaction but works quite well as an additional stimulus. After the meeting, I often have so much energy that I want to continue immediately.

TLDR

You see, feedback and collaboration in writing are vital to us. We like to experiment with new methods and tools to improve our writing activities together. Feedback is not always easy to give or accept, still it creates enormous advantages to writing when we share our writing activities.

Those of you who are MB.ioneers and now feel like writing, please contact me.
To the readers who don't work at Mercedes-Benz.io yet. What do you think about the Mob Writing approach and how do you handle the feedback process when writing your articles?

Everyone can write. And even better when doing it together!

P.S.: Incorporating feedback into this article about feedback was particularly exciting. Caught in the endless loop of reflecting on feedback.

Photo by Joanna Kosinska and Tamanna Rumee on Unsplash

Use Tailwind Without Tailwind

Helmuth Saatkamp — Tue, 23 Aug 2022 14:38:00 +0000

Tailwind is one of those very controversial things, some people argue that it is the best since sliced bread, others it is a tool sent by the devil itself. Nonetheless, this is not an article about if you should use it or not, there are already plenty of those articles about the pros and cons on the internet.

What makes Tailwind good is the documentation, you may not agree on the “naming” but for every class that you can use there is an equivalent showing how to use it with CSS, for that, the team has done an outstanding job.

Tailwind is super fun to work with after you pass the initial learning threshold, but as a Developer, you still need to understand CSS to use it correctly.

CSS is not hard nor is broken.

In the end, it is just a tool to help you to write CSS, and as a tool, it limits the options of what you could do, for example, you would never be able to use a custom grid layout with Tailwind only, as the one below:

Mobile	Desktop

^{Source: https://webkit.org/demos/css-grid/}

In this article, you will learn how to use Tailwind documentation to write your CSS styles. The following topics will be discussed:

Preflight
Theme
Styles

The idea is to have the full power to write your CSS together with the cool ideas and patterns created by the Tailwind team. So let's get started.

Preflight

Preflight is a set of base styles for Tailwind projects that are designed to smooth over cross-browser inconsistencies and make it easier for you to work within the constraints of your design system.

Here you have basically to copy the preflight.css created by them.

/* preflight.css */
*,
::before,
::after {
  box-sizing: border-box;
  border-width: 0;
  border-style: solid;
  border-color: currentcolor;
}

html {
  line-height: 1.5;
  text-size-adjust: 100%;
  tab-size: 4;
  font-family: system-ui;
}

body {
  margin: 0;
  line-height: inherit;
}

hr {
  height: 0;
  color: inherit;
  border-top-width: 1px;
}

abbr:where([title]) {
  text-decoration: underline dotted;
}

h1,
h2,
h3,
h4,
h5,
h6 {
  font-size: inherit;
  font-weight: inherit;
}

a {
  color: inherit;
  text-decoration: inherit;
}

b,
strong {
  font-weight: bolder;
}

code,
kbd,
samp,
pre {
  font-family:
    "fontFamily.mono",
    ui-monospace,
    SFMono-Regular,
    Menlo,
    Monaco,
    Consolas,
    "Liberation Mono",
    "Courier New",
    monospace;
  font-size: 1em;
}

small {
  font-size: 80%;
}

sub,
sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}

sub {
  bottom: -0.25em;
}

sup {
  top: -0.5em;
}

table {
  text-indent: 0;
  border-color: inherit;
  border-collapse: collapse;
}

button,
input,
optgroup,
select,
textarea {
  font-family: inherit;
  font-size: 100%;
  font-weight: inherit;
  line-height: inherit;
  color: inherit;
  margin: 0;
  padding: 0;
}

button,
select {
  text-transform: none;
}

button,
[type="button"],
[type="reset"],
[type="submit"] {
  appearance: button;
  background-color: transparent;
  background-image: none;
}

:-moz-focusring {
  outline: auto;
}

:-moz-ui-invalid {
  box-shadow: none;
}

progress {
  vertical-align: baseline;
}

::-webkit-inner-spin-button,
::-webkit-outer-spin-button {
  height: auto;
}

[type="search"] {
  appearance: textfield;
  outline-offset: -2px;
}

::-webkit-search-decoration {
  appearance: none;
}

::-webkit-file-upload-button {
  appearance: button;
  font: inherit;
}

summary {
  display: list-item;
}

blockquote,
dl,
dd,
h1,
h2,
h3,
h4,
h5,
h6,
hr,
figure,
p,
pre {
  margin: 0;
}

fieldset {
  margin: 0;
  padding: 0;
}

legend {
  padding: 0;
}

ol,
ul,
menu {
  list-style: none;
  margin: 0;
  padding: 0;
}

textarea {
  resize: vertical;
}

input::placeholder,
textarea::placeholder {
  opacity: 1;
  color: #9ca3af;
}

button,
[role="button"] {
  cursor: pointer;
}

:disabled {
  cursor: default;
}

img,
svg,
video,
canvas,
audio,
iframe,
embed,
object {
  display: block;
  vertical-align: middle;
}

img,
video {
  max-width: 100%;
  height: auto;
}

That's it, just add this CSS to your project.

Theme

The theme file is where you define your project’s color palette, type scale, fonts, breakpoints, border radius values, and more.

This is the most important part, getting the same idea of the tailwind.config.js file where you can customize your theme, create a theme file following the Tailwind definitions:

/* theme.css */
:root {
  --size-0-5: 0.125rem; /* spacing:0.5 */
  --size-1: 0.25rem; /* spacing:1 */
  --size-1-5: 0.375rem; /* spacing:1.5 */
  --size-2: 0.5rem; /* spacing:2 */
  --size-2-5: 0.625rem;
  --size-3: 0.75rem;
  --size-3-5: 0.875rem;
  --size-4: 1rem;
  --size-5: 1.25rem;
  --size-6: 1.5rem;
  --size-7: 1.75rem;
  --size-8: 2rem;
  --size-9: 2.25rem;
  --size-10: 2.5rem;
  --size-11: 2.75rem;
  --size-12: 3rem;
  --size-14: 3.5rem;
  --size-16: 4rem;
  --size-20: 5rem;
  --size-24: 6rem;
  --size-28: 7rem;
  --size-32: 8rem;
  --size-36: 9rem;
  --size-40: 10rem;
  --size-44: 11rem;
  --size-48: 12rem;
  --size-52: 13rem;
  --size-56: 14rem;
  --size-60: 15rem;
  --size-64: 16rem;
  --size-72: 18rem;
  --size-80: 20rem;
  --size-96: 24rem;
  --size-xs: 20rem; /* 320px */
  --size-sm: 24rem; /* 384px */
  --size-md: 28rem; /* 448px */
  --size-lg: 32rem; /* 512px */
  --size-xl: 36rem; /* 576px */
  --size-2xl: 42rem; /* 672px */
  --size-3xl: 48rem; /* 768px */
  --size-4xl: 56rem; /* 896px */
  --size-5xl: 64rem; /* 1024px */
  --size-6xl: 72rem; /* 1152px */
  --size-7xl: 80rem; /* 1280px */
  --size-full: 100%;
  --size-fit: fit-content;
  --size-min: min-content;
  --size-max: max-content;
  --size-auto: auto;
  --size-none: none;
  --size-prose: 65ch;
  --size-screen-width: 100vw;
  --size-screen-height: 100vh;
  --size-screen-xs: 480px;
  --size-screen-sm: 640px;
  --size-screen-md: 768px;
  --size-screen-lg: 1024px;
  --size-screen-xl: 1280px;
  --size-screen-2xl: 1536px;
  --grid-1: repeat(1, minmax(0, 1fr));
  --grid-2: repeat(2, minmax(0, 1fr));
  --grid-3: repeat(3, minmax(0, 1fr));
  --grid-4: repeat(4, minmax(0, 1fr));
  --grid-5: repeat(5, minmax(0, 1fr));
  --grid-6: repeat(6, minmax(0, 1fr));
  --grid-7: repeat(7, minmax(0, 1fr));
  --grid-8: repeat(8, minmax(0, 1fr));
  --grid-9: repeat(9, minmax(0, 1fr));
  --grid-10: repeat(10, minmax(0, 1fr));
  --grid-11: repeat(11, minmax(0, 1fr));
  --grid-12: repeat(12, minmax(0, 1fr));
  --border: 1px;
  --border-0: 0;
  --border-2: 2px;
  --border-4: 4px;
  --border-8: 8px;
  --ring: 0 0 0 var(--border);
  --ring-2: 0 0 0 var(--border-2);
  --ring-4: 0 0 0 var(--border-4);
  --ring-8: 0 0 0 var(--border-8);
  --rounded: 0.25rem;
  --rounded-sm: 0.125rem;
  --rounded-md: 0.375rem;
  --rounded-lg: 0.5rem;
  --rounded-xl: 0.75rem;
  --rounded-2xl: 1rem;
  --rounded-3xl: 1.5rem;
  --rounded-full: 9999px;
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 10%), 0 1px 2px -1px rgb(0 0 0 / 10%);
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 5%);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 10%), 0 2px 4px -2px rgb(0 0 0 / 10%);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 10%), 0 4px 6px -4px rgb(0 0 0 / 10%);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 10%), 0 8px 10px -6px rgb(0 0 0 / 10%);
  --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 25%);
  --shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 5%);
  --font-weight-thin: 100;
  --font-weight-extralight: 200;
  --font-weight-light: 300;
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
  --font-weight-extrabold: 800;
  --font-weight-black: 900;
  --line-spacing-xs: 1rem;
  --line-spacing-sm: 1.25rem;
  --line-spacing-md: 1.5rem;
  --line-spacing-lg: 1.75rem;
  --line-spacing-xl: 1.75rem;
  --line-spacing-2xl: 2rem;
  --line-spacing-3xl: 2.25rem;
  --line-spacing-4xl: 2.5rem;
  --line-spacing-5xl: 1;
  --line-spacing-6xl: 1;
  --line-spacing-7xl: 1;
  --line-spacing-8xl: 1;
  --line-spacing-9xl: 1;
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-md: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;
  --text-4xl: 2.25rem;
  --text-5xl: 3rem;
  --text-6xl: 3.75rem;
  --text-7xl: 4.5rem;
  --text-8xl: 6rem;
  --text-9xl: 8rem;
  --color-canvas: #f9fafb; /* gray:50 */
  --color-contrast: #27272a; /* zinc:800 */
  --color-contrast-50: #fafafa; /* zinc:50 */
  --color-contrast-100: #f4f4f5; /* zinc:100 */
  --color-contrast-200: #e4e4e7; /* zinc:200 */
  --color-contrast-300: #d4d4d8; /* zinc:300 */
  --color-contrast-400: #a1a1aa; /* zinc:400 */
  --color-contrast-500: #71717a; /* zinc:500 */
  --color-contrast-600: #52525b; /* zinc:600 */
  --color-contrast-700: #3f3f46; /* zinc:700 */
  --color-contrast-800: #27272a; /* zinc:800 */
  --color-contrast-900: #18181b; /* zinc:900 */
  --color-primary-backdrop: #bfdbfe; /* blue:200 */
  --color-primary-focus: #93c5fd; /* blue:300 */
  --color-primary: #2563eb; /* blue:600 */
  --color-primary-content: #1e40af; /* blue:800 */
  --color-primary-contrast: #fff;
  --color-error-backdrop: #fecdd3; /* rose:200 */
  --color-error-focus: #fda4af; /* rose:300 */
  --color-error: #f43f5e; /* rose:600 */
  --color-error-content: #9f1239; /* rose:800 */
  --color-error-contrast: #fff;
  --color-success-backdrop: #bbf7d0; /* green:200 */
  --color-success-focus: #86efac; /* green:300 */
  --color-success: #22c55e; /* green:600 */
  --color-success-content: #166534; /* green:800 */
  --color-success-contrast: #fff;
  --color-content-heading: #111827; /* gray:900 */
  --color-content-body: #1f2937; /* gray:800 */
  --color-content-secondary: #374151; /* gray:700 */
  --color-content-tertiary: #6b7280; /* gray:500 */
  --color-content-disabled: #9ca3af; /* gray:400 */
  --color-content-contrast: #d1d5db; /* gray:300 */
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-canvas: #27272a; /* zinc:800 */
    --color-contrast: #fff;
    --color-contrast-50: #18181b; /* zinc:900 */
    --color-contrast-100: #27272a; /* zinc:800 */
    --color-contrast-200: #3f3f46; /* zinc:700 */
    --color-contrast-300: #52525b; /* zinc:600 */
    --color-contrast-400: #71717a; /* zinc:500 */
    --color-contrast-500: #a1a1aa; /* zinc:400 */
    --color-contrast-600: #d4d4d8; /* zinc:300 */
    --color-contrast-700: #e4e4e7; /* zinc:200 */
    --color-contrast-800: #f4f4f5; /* zinc:100 */
    --color-contrast-900: #fafafa; /* zinc:50 */
    --color-primary-backdrop: #93c5fd; /* blue:300 */
    --color-primary-focus: #3b82f6; /* blue:500 */
    --color-primary: #2563eb; /* blue:600 */
    --color-primary-content: #1e40af; /* blue:800 */
    --color-primary-contrast: #fff;
    --color-error-backdrop: #fda4af; /* rose:300 */
    --color-error-focus: #f43f5e; /* rose:500 */
    --color-error: #e11d48; /* rose:600 */
    --color-error-content: #9f1239; /* rose:800 */
    --color-error-contrast: #fff;
    --color-success-backdrop: #86efac; /* green:300 */
    --color-success-focus: #22c55e; /* green:500 */
    --color-success: #16a34a; /* green:500 */
    --color-success-content: #166534; /* green:800 */
    --color-success-contrast: #fff;
    --color-content-heading: #f9fafb; /* gray:50 */
    --color-content-body: #e5e7eb; /* gray:200 */
    --color-content-secondary: #d1d5db; /* gray:300 */
    --color-content-tertiary: #6b7280; /* gray:500 */
    --color-content-disabled: #4b5563; /* gray:600 */
    --color-content-contrast: #374151; /* gray:700 */
  }
}

@custom-media --xs (min-width: var(--size-screen-xs));
@custom-media --sm (min-width: var(--size-screen-sm));
@custom-media --md (min-width: var(--size-screen-md));
@custom-media --lg (min-width: var(--size-screen-lg));
@custom-media --xl (min-width: var(--size-screen-xl));
@custom-media --xxl (min-width: var(--size-screen-2xl));

To use those variables, you can declare as follows:

.example {
  padding: var(--size-3); /* p-3 */
  border-radius: var(--rounded-lg); /* rounded-lg */
  box-shadow: var(--shadow-lg); /* shadow-lg */
  font-size: var(--text-sm); /* text-sm */
  line-height: var(--line-spacing-sm); /* text-sm */
}

You can define your CSS variables to have the same values defined in the Tailwind, so you can get through their docs and use their style. But you wouldn't need to define a variable for every single class, some classes like inline-flex can be directly translated to display: inline-flex.

The good thing is that is one dependency less in your project, no matter how fast the tailwind (re)builds the CSS it will never the faster than having it directly declared, and the main point is that gives to the developer the full control. The downside is that you lose their syntax sugar.

Styles

Taking what you learned and applying it to a real-world scenario: Imagine you are building a UI Library. You start to build a badge component. This component should have options to change the size, color, and format, so you can create the following style:

/* badge.css */
.badge {
  display: inline-flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: center;
  white-space: nowrap;
  padding: var(--size-1) var(--size-2);
  text-align: center;
  vertical-align: middle;
  font-size: var(--badge-font-size, var(--text-md));
  line-height: var(--badge-line-height, var(--line-spacing-md));
  font-weight: var(--font-weight-semibold);
  border: var(--badge-border, var(--border) solid var(--color-contrast-200));
  border-radius: var(--badge-border-radius, var(--rounded-lg));
  background-color: var(--badge-background-color, var(--color-contrast-50));
  color: var(--badge-color, var(--color-content-body));

  &.is-pill {
    --badge-border-radius: var(--rounded-full);
  }

  &.is-xs {
    --badge-font-size: var(--text-xs);
    --badge-line-height: var(--line-spacing-xs);
  }

  &.is-sm {
    --badge-font-size: var(--text-sm);
    --badge-line-height: var(--line-spacing-sm);
  }

  &.is-lg {
    --badge-font-size: var(--text-lg);
    --badge-line-height: var(--line-spacing-lg);
  }

  &.is-xl {
    --badge-font-size: var(--text-xl);
    --badge-line-height: var(--line-spacing-xl);
  }

  &.is-info {
    --badge-border: var(--border) solid var(--color-primary-focus);
    --badge-background-color: var(--color-primary);
    --badge-color: var(--color-primary-contrast);
  }

  &.is-error {
    --badge-border: var(--border) solid var(--color-error-focus);
    --badge-background-color: var(--color-error);
    --badge-color: var(--color-error-contrast);
  }

  &.is-success {
    --badge-border: var(--border) solid var(--color-success-focus);
    --badge-background-color: var(--color-success);
    --badge-color: var(--color-success-contrast);
  }

  &.is-contrast {
    --badge-border: var(--border) solid var(--color-contrast-800);
    --badge-background-color: var(--color-contrast-700);
    --badge-color: var(--color-content-contrast);
  }
}

Selector	Description
:host/:host(name)	Selects the shadow host element or if it has a certain class.
:host-context(name)	Selects the shadow host element only if the selector given as the function's parameter matches the shadow host's ancestor(s) in the place it sits inside the DOM hierarchy.
::slotted()	Selects a slotted element if it matches the selector.
::part()	Selects any element within a shadow tree with a matching part attribute.

Forem: Mercedes-Benz.io

GitHub Copilot in Frontend Development

1. Define a Context

2. Break Down the Problem

3. Define an Outcome

4. Prompt Examples

Prototyping

Create a Method

Create a Regex

Convert X to Y

Code Refactoring

Debugging

Explain a Method

Code Insight

Documentation

Document a Method

Testing

Create Test

Add Test Cases

Learning

How To

4. Conclusion

Improving Your Development Documentation Project (2 of 3)

Introduction

Step 1 - Design a User Survey

Why These Questions?

MS Forms

Step 2 - Schedule the Survey

Step 3 - Survey Time

API Testing with Java and Spring Boot Test - Part 2: Improving the solution

Refactoring the Object mapping

Improving the response validation

Executing the tests over multiple environments

Executing the test suit

Improving Your Development Documentation Project (1 of 3)

Introduction

Know Your Ground

Step 1 - Organize Your Improvement Project

Space Structure

Step 2 - Identify Your Documentation Issues

API Testing with Java and Spring Boot Test - Part 1: The basic setup

Choosing the language and framework

Setting up the project

Step 1: Create the project

Step 2: Changing the Main class

Step 3: Create a Service to manage your API

Step 4: Add a test case

Automated Frontend Workflow

Table of Contents

Project

Setup

Prettier

Sass

TypeScript

Vite

Vitest

VitePress

Storybook

ESLint

Stylelint

Git

Git setup

Git hooks

Lefthook

GitHub Actions

Code Analysis

Linters

Testing

Branch Protection

Docs

Conclusion

ARTICLE WRITING: Feedback and how we integrated it with a developer

The importance of feedback and its influence on your writing

Feedback

Types of feedback

Guidelines regarding Feedback

Giving feedback the right way

Prepare yourself for the feedback

Receiving feedback and how to deal with it.

The Mercedes-Benz.io way for feedback and collective writing

Step 2: Changing the `Main` class

Step 3: Create a `Service` to manage your API

The `<slot>` element