DEV Community: Patrick R

Automated JIRA release notes

Patrick R — Sun, 16 Aug 2020 10:52:49 +0000

This is my submission to the #ActionsHackathon. It is a github action designed to generate release notes based on commit messages.

My Workflow

My tendency to get tunnel vision when working has often led me to lose track of events happening in my team. The number of projects and repos being large, keeping track of release cycles had me worried.

I built the patrixr/jira-release-notes action with the intent of being notified by email whenever one of our (many) apps got released.

It works as follows:

It compares two git refs and reads all the new commits (typically when a pull request is merged)
It finds JIRA ticket references in the commit messages (e.g ABC-123)
Using jira credentials, it will retrieve the ticket info
It will generate release notes in Markdown based on those tickets

The available outputs are:

PDF - The action will always generate a pdf file
Email - Optional - If provided with a Sendgrid key and recipients, will forward the notes via email

Submission Category:

DIY Deployments

Yaml File or Link to Code

For details, head over to the github repo:

patrixr / jira-release-notes

🔀 Github action to generate release notes based on JIRA tickets

Jira Release Notes

This action generates release notes based on JIRA ticket numbers found in commits, and creates a PDF file. It can also email you the notes.

Built as part of the #ActionsHackathon

How it works

You need to provide 2 refs to the action, head and base. The action steps are as followed:

Fetch all the commits between the head and base refs
Find any reference to JIRA ticket numbers, based on the jira-code you provide
Will fetch the ticket titles using the jira-host, jira-username and jira-password you provide
If pdf is set to true 4.1. Will generate a pdf with the list of changed tickets, and output the file path under the pdf variable otherwise 4.2. Will generate markdown with the list of changed tickets, and output it under the markdown variable
(OPTIONAL) If the email-to and sendgrid-api-key are provided, and email will be sent…

View on GitHub

You can also find it on the Marketplace

Usage example

name: Forward release notes

on:
  pull_request:
    types: [closed]
    branches:
      - live

jobs:
  release-notes:
    runs-on: ubuntu-latest
    if: github.event.pull_request.merged == true
    steps:
    - uses: actions/checkout@v2
    - name: Generate and email notes
      uses: actions/jira-release-notes@v1.0.1
      id: pdf_generator
      with:
        head: ${{github.event.pull_request.head.sha}}
        base: ${{github.event.pull_request.base.sha}}
        jira-code: 'ABC'
        jira-host: jira.mycompany.org
        jira-username: ${{secrets.jira_username}}
        jira-password: ${{secrets.jira_password}}
        email-to: 'john@mycompany.org,jane@mycompany.org'
        sendgrid-api-key: ${{secrets.sendgrid_api_key}}
        app-name: 'My Awesome Service'
        unshallow: true
    - name: Process the pdf
      run: echo "The generated pdf was ${{ steps.pdf_generator.outputs.pdf }}"

Additional Resources / Info

We have been using this tool within the Goodcity Project, a system designed to gather, managed and distribute donations. The project lives under the umbrella of the non-profit Crossroads Foundation. Our work is available on github.

Ideas for improvement

Multiple email service support
Custom Markdown template for email/pdf structure
Support for other project management platforms

Feel free to reach out for any issue or suggestions :)

Happy coding everyone !

Cheers !

Design pattern: JS Functional Chains

Patrick R — Tue, 15 Oct 2019 08:20:17 +0000

Functional Chains: Implementation

Writing a serializable chainable functional API in Javascript.

All of the work below can be found in this functional chain builder. A ready-made and reusable npm module allowing you to generate a small API.

Introduction

I've long thought chainable APIs were both elegant and descriptive.

And started playing around with a functional and stateless implementation, as a fun experiment.

The chain

Here's an example the API I'm thinking of :

const operation = multiplyBy(2)
  .and.subtract(6)
  .and.divideBy(2);

operation(33); // => 30

The result should be a re-usable function that applies the different commands in order.

Serialization

Instead of applying the operations immediately, this API is designed to return a function. The reason for that is to allow serialization.

Here's an example of how that would look like :

analyse(operation);

// output =>
[
  { multiplyBy:  [2] },
  { subtract: [6]},
  { divideBy: [2] }
]

What are the benefits of serialization :

Testing

Serialization can be beneficial in testing: we can assert the operations are correct. Possibly replacing end to end tests with simpler unit tests\

Networking

A serialized operation, is one that can be sent over the wire, expanding the use cases of the chain.

Exploiting JavaScript

Let's take a quick look at the language features that allow this to be possible.

Functions are first-class objects

A programming language is said to have First-class functions when functions in that language are treated like any other variable

source: mozilla.org

What does that mean for us:

we can pass functions around as arguments
we can set properties to functions

Scoping and closures

Closures are simpler to use than they are to explain. But here's what matters to us:

If a function creates another function, that new one can access its creator's scope. It can in turn create a new function itself, and then again, and again... building a chain.

Implementing the chain

Defining the API

Before we actually write the chain, we need to define our api:

const API = {
  add(val) {
    return num => num + val
  },

  subtract(val) {
    return num => num - val
  },

  multiplyBy(val) {
    return num => num * val
  },

  divideBy(val) {
    return num => num / val
  }
}

This is pretty straightforward, each method returns a function that will apply the desired operation.

Creating a wrapper function

We've discussed the idea of returning functions out of functions. So let's create a base function that receives a chain, and returns the completed operation.

function Wrap(chain = []) {
    let compute = (num) => {
        // Iterate through the chain and applies the calculations
        return chain.reduce((mem, fn) => fn(mem), num);
    }

    return compute;
}

At this point, we have no means of adding anything to the chain. So let's add methods to our compute function, one for each that was defined previously.

for (let key in API) {
  const fn = API[key];
  compute[key] = () => {
     ...
  }
}

We already know we need to return a function, that's the expected result of our chain. We also know, that this function should allow more functions to be chained.

Most of you saw this coming, we can simply return our Wrap, which does exactly that. The chaining takes place by providing it an extended chain.

function Wrap(chain = []) {
    let compute = (num) => {
      // Iterate through the chain and applies the calculations
      return chain.reduce((mem, fn) => fn(mem), num);
    }

    for (let key in API) {
      const fn = API[key];
      compute[key] = (num) => {
        return Wrap([ ...chain, fn(num) ]);
      }
    }

    return compute;
}

Currently, this usage would work :

const operation = Wrap()
  .multiplyBy(2)
  .subtract(6)
  .divideBy(2);

operation(33); // => 30

Prettifying our API

We now have a working chainable API. But the need to have Wrap() prefixed to any chain is not of adequate elegance.

Exporting user-friendly methods

We want to be able to start our chain through one of the API's method. An easy way to achieve this is to have our module export those methods, with the wrap included.


// (API Object)

// (Wrap function)

module.exports = Object
    .keys(API)
    .reduce((res, key) => {
      const fn = API[key];
      res[key] = (...params) => Wrap([ fn(...params) ]);
      return res;
    }, {});

We essentially hide the initial wrap inside the methods.

Here's how our usage currently looks :

const { multiplyBy } = require('./mychain');

const operation = multiplyBy(2)
  .subtract(6)
  .divideBy(2);

operation(33); // => 30

Already looking much better.

Adding semantics

Part of our initial design was to have an optional and key word between each chain member. Although the need for that is arguable, let's do it for science.

And the implementation couldn't be any simpler :

function Wrap(chain = []) {
    let compute = (num) => { ... }

    for (let key in API) {
      const fn = API[key];
      compute[key] = (num) => { ... }
    }

    // Semantics of choice
    compute.and = compute;
    compute.andThen = compute;
    compute.andThenDo = compute;

    return compute;
}

Which brings us to our expected usage :

const operation = multiplyBy(2)
  .and.subtract(6)
  .andThen.divideBy(2);

operation(33); // => 30

Next Step: Serialization

Thanks for reading through part one of my functional chain article.

In order to keep them short, I will continue the topic of serialization in a separate article.

If anyone has experience building chainable APIs, I would love to hear your approach and use cases.

Cheers,

Patrick

React: Writing a custom API hook

Patrick R — Tue, 20 Aug 2019 06:40:54 +0000

Let's write a handy custom react hook to take care of the usual API logic we've all written time and time again.

Introduction

After a couple of years away from React, I'm re-educating myself on the best practices. This means : Hooks

One of the very (very) common flow we find across our apps is that of loading data from the API and displaying it.

It usually looks somewhat like this :

This has a tendency to result in very cluttered components. Let's use our newfound knowledge of hooks to solve this.

Designing the hook

Based on the flow described above, it's pretty easy to define the data that we want our hook to provide. It will return :

The response data
A loading flag
An error (nulled on success)
A retry method

Given that I still appreciate delegating the request code to a service class, my thought is to have the hook call the service.

Leading to the following usage:

const [ user, isLoading, error, retry ] = useAPI('loadUserById', 56);

Preparing the API service

Let's use a little service class, in which we can place all of our beautiful ajax code.

class APIService {
    async loadUsers() {
        // ... ajax magic
    }

    async loadUserById(id) {
        // ... ajax magic
    }
} 

export default new APIService();

Writing the hook

Our goal here is simply to combine standard react hooks to create all of our required fields.

The state

React already provides us with the useState hook to create and update state properties.

Let's generate our fields :

function useAPI(method, ...params) { 

  const [data, setData]           = useState(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, onError]          = useState(null);

}

Calling the service

The React hook that comes in play here is useEffect, in which we can run our asynchronous code.

useEffect(() => {
   // ... async code
}, []);

However, we've decided that the hook would return a retry method. So let's move the asynchronous code to its own function

const fetchData = async () => {
   // ... async code
}

useEffect(() => { fetchData() }, []);

Let's now call the correct service method, based on the hook's arguments

const fetchData = async () => {
  // Clear previous errors
  onError(null);

  try {
    // Start loading indicator
    setIsLoading(true);

    // Fetch and set data
    setData(await APIService[method](...params));
  } catch (e) {
    // Set the error message in case of failure
    setError(e);
  } finally {
    // Clear loading indicator
    setIsLoading(false);
  }
};

useEffect(() => { fetchData() }, []);

Result

And voila ! Our hook is ready for consumption.

function useAPI(method, ...params) {
    // ---- State
    const [data, setData]           = useState(null);
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError]         = useState(null);

    // ---- API
    const fetchData = async () => {
      onError(null);
      try {
        setIsLoading(true);
        setData(await APIService[method](...params));
      } catch (e) {
        setError(e);
      } finally {
        setIsLoading(false);
      }
    };

    useEffect(() => { fetchData() }, []);

    return [ data, isLoading, error, fetchData ];
}

Usage in a component

Let's write a little example of how that might be used in a component

function HomeScreen() {
  const [ users, isLoading, error, retry ] = useAPI('loadUsers');

  // --- Display error
  if (error) {
    return <ErrorPopup msg={error.message} retryCb={retry}></ErrorPopup>
  }

  // --- Template
  return (
    <View>
      <LoadingSpinner loading={isLoading}></LoadingSpinner>
      {
          (users && users.length > 0) &&
            <UserList users={users}></UserList>
      }
    </View>
  );
}

Conclusion

There are many ways to avoid re-writing common code across the application.

In the past I've often delegated some of that to a Store, or used Mixins to create components with all that logic ready to use.

Custom hooks give us a whole new flavour and open up new strategies for dealing with problems.

Happy to witness the evolution of practices.

Cheers,

Patrick

Publishing my vitals over the cloud

Patrick R — Mon, 12 Aug 2019 11:44:40 +0000

Having grown up with an over-protective and worrying father, my moving away never sat quite well with him.

After years of answering regular text messages assessing my well-being, I've decided to try out a different approach.

The Project

The idea is to build a dashboard that my father can regularly check to ensure that I'm alive and well. Hopefully reducing his anxiety and paranoia over my inescapable impending doom.

I decided to leverage my enthusiasm for Fitbit products with my understanding of the cloud to build this.

I settled on a VueJS + ExpressJS tech stack for fast prototyping. Details can always be found on my github.

Here's a very basic diagram of the concept

Using the Fitbit API

Having both a connected scale and wristband, the Fitbit API gives me access to a multitude of data points:

Heart rate
Daily activity
Steps
Body (Weight/Fat/BMI)
Sleep info
and many more

The goal is to have our server periodically retrieve data through the api.

Step 1: Registering an application

First things first, let's head over to the Fitbit developer console and register an application.

This will provide us with a CLIENT_ID/CLIENT_SECRET key pair required for an OAuth2 authentication.

Important :

The detailed heart rate data, also known as "Heart Rate Intraday Time Series" , is currently only available through the Personal app type, which we are using today.

Given that this project only displays data, the app should be marked as Read-Only.

Step 2: Authenticate

For a quick and painless authentication, I am using the passport-fitbit-oauth2 module.

Creating the Strategy


const Strategy = new FitbitStrategy({
  clientID:     config.CLIENT_ID,
  clientSecret: config.CLIENT_SECRET,
  callbackURL:  config.CALLBACK_URL,
  scope: [
    'sleep', 'weight', 'activity',
    'heartrate', 'location', 'profile',
    'nutrition', 'social'
  ]
}, (access_token, refresh_token, profile, done) => {
    // store the tokens
    done( ... );
})

Hooking it up to ExpressJS

passport.use(Strategy);

const authenticate = passport.authenticate('fitbit', {
  session: false,
  successRedirect: '/',
  failureRedirect: '/error'
});

app.get('/login', once, authenticate);
app.get('/callback', once, authenticate);

Access tokens eventually expire, that can be detected by the return of a 401 from the API. A sign for us to proceed with the Token Refresh.

Step 3: Retrieving data

Now that we have the Fitbit access token, we can start making calls to their Web API.

Here's an example of how to retrieve todays' Heart Rate Intraday Time Series:

GET https://api.fitbit.com/1/user/-/activities/heart/date/today/1d/1min.json

The server then returns the following JSON :

{
    "activities-heart-intraday": {
        "dataset": [
            {
                "time": "00:01:00",
                "value": 64
            },
            {
                "time": "00:02:00",
                "value": 63
            },
            //...
        ],
        "datasetInterval": 1,
        "datasetType": "minute"
    }
}

Building the dashboard

With this being a passion project, I pulled in a few libraries I love to quickly get going.

Vue as a framework, a choice of comfort
Vue Trend for slick looking graphs
Font Awesome for the icons, a classic
Animate.css exclusively for the heart pulsing animation

After a bit of wiring around, the following was birthed :

Securing the app

The web app exposes very personal data of mine, notably my fat percentage which can be seen sky rocketing around the Christmas holidays.

For this reason, I hooked up my own tiny CMS (Pocket), which provides me with users, access control and an admin panel out of the box.

Improvement ideas

Here are a few things I'm thinking of adding or have considered :

My nutrition (would require me to input everything I eat)
A button that reminds me to drink water
My location, that may be a bit too much

Conclusion

Despite this project being extremely small and simplistic, I enjoyed the concept of making family members happier through technology.

Would love to hear your thoughts and experiences in writing code for well being.

Cheers,

Patrick

An outlook on state management

Patrick R — Tue, 18 Jun 2019 02:19:19 +0000

This article takes a step back to reflect on today's state management practices in front-end web development.

Not a tutorial

With today's resources, it would likely take you less than a minute to discover an abundance of great tech guides on how to write robust web applications.

If you've spent a bit of time doing that, you've surely landed on tutorials for "state container" libraries and patterns, aka "stores". Most famously Redux which is often used in React apps, or it's Vue counterpart Vuex.

Frankly, I could not write better tutorials if I tried. Instead, what I want to do here is spend a moment to think about WHY we are doing all of that, to learn what it truly means to write a good app.

Before we continue, I will give a quick shoutout to Hassan Djirdeh's great tutorial on Managing State in Vue.js. If you are looking for a more technical and hands-on article, definitely check it out.

What is a stateful system ?

If you've never asked yourself the question of whether your system was of a stateful nature, then the odds are that it was.

Let's try to define it as best we can :

An application is categorized as stateful if it stores data that will in turn affect the behaviour and output of the system

To give that definition some context, let's take a simple example :

Example: A user logs into your application. The code retrieves a piece of user related data and stores it. The next time you open the application, the app reads that stored data, understands that you are logged in and directly opens your profile page.

In the above example the state, which consists of the user's data, affects the behaviour of the app which here decides to show you a different page.

Writing an app in that manner is so incredibly common that we rarely take a moment to think about it.

... but we really should

Side effects

Here is a common definition of a software bug

A software bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways

Source: Wikipedia

Let's bring our attention to one word:

... or to behave in unintended ways

Also present in the definition of a stateful system:

...will in turn affect the behaviour and output of the system

Though this would seem obvious to some, poorly managing our data is a direct cause of bugs, leading to instability. One common term is side effects.

All of this loops back to data:

Data is unpredictable
Data can be faulty
Data can be mutated

Let's tie this all together with some scenarios to illustrate those side-effects.

Case 1: Unexpected mutation

Let's start with a sample of data:

{
    message: 'This is my first post',
    timestamp: 1560044669311
}

We decide to display the date as a user friendly string showing how long ago the message was posted e.g "1 hour ago"

Our junior developer, not knowing any better, decides to format it nicely, mutating the data in the process:

post.timestamp = moment(post.timestamp).fromNow()

If reading this line gave you an uneasy feeling, congratulations, you understand the dangers of data mutation.

Fast forward to moments later in the application's life, when another piece of code reads that post, expecting a number value.

console.log(post.timestamp); // => '1 hour ago'
new Date(post.timestamp); // => Invalid Date

This, as you can expect, returns an invalid date, eventually leading up to a bug.

Case 2: Multiple sources of data

A JWT token is returned after a successful user login. It is added to the local storage and attached to requests when connecting to the server.

The app is structured with multiple service classes, nicely representing the different functionalities of the API, e.g

class UserService { ... }
class SearchService { ... }

It wouldn't be too far fetched to have all of them hold an authToken property to use when calling the API.

e.g

apiCall() {
    ajax('/some/url', { Authorization: this.authToken })
}

And with every user based application, comes a logout feature:

logout() {  
    localStorage.setItem('jwt', null);
    UserService.clearToken();
    SearchService.clearToken();
}

That kinda works, not great but let's go with it for the sake of making our point.

Now comes a feature request, we want our user to be able to interact with his playlists. Simple, we add a new service :

class PlaylistService { ... }

!Problem! we forgot to clear the token of that new service in the logout method.

What would now happen if I logged out of the app, we can imagine a multitude of bugs:

The app could modify user data even after logout
The app could act on behalf of the wrong user
The app could believe a user is still logged in

Some would think that there's nothing inherently wrong in the architecture we're portraying but we shouldn't need to remember to clear the PlaylistService token. In the robust system we're about to build, we won't need to.

How resources define practices

We don't need to go far back in history to remember when a computer's memory was measured in megabytes, even kilobytes.

When we work on systems with limited resources, there's a good incentive in mutating data and reusing memory. The risks of side effects in exchange of a low memory footprint is a fair tradeoff.

Today resources are usually plentiful. We can allow ourselves to use more data for the sake of stability.

What does that mean in every day life:

Writing pure functions
Recreating alternate datasets instead of mutating them
Using language features to secure data (e.g const)
Carefully selecting libraries e.g
- Immutable.js as its name suggests, it is specifically made to provide non-mutable structures
- Moment.js although a very powerful tool, it is also known for having mutating methods, tread carefully

Practices change over time and across fields. Web development is now seeing patterns borrowed from functional programming as the two worlds start to mesh together. A great example of that is Elm, a functional language that compiles to JavaScript.

Is the grass greener on the other side ?

We've gone over a lot of downsides of building stateful systems. One question arises: Could we build stateless web apps ?
Although stateless designs have existed on the backend side for a while, it is not a question we often ask ourselves for front-end apps.

Nothing prevents us technically from doing so, but applications are often designed as stateful. An example of that would be a shopping cart: a feature revolving around the ability to store and edit data.

Building an app with a state, although prone to side-effects, offers a lot of convenience often taken for granted. The absence of local data would double efforts only to get around that restriction.

So we know that the state is not going away, and we know that it is prone to errors. So how can we manage it efficiently.

The birth of flux

The most popular store containers are derived from the Flux pattern. Despite the differences we may find, they all try to solve the same problem and share core values.

Formalization

By their sheer existence, those containers bring the state to the front line of the application, and under the eyes of developers.

No longer on the sidelines, it transforms the data into something official, noticeable and therefore worth taking care of.

Direct access

Apps are typically built as a tree structure of components. The data cascades down the tree, being passed on and on.

That opens up a great number of opportunities for mishandling data. We could jokingly call that a software version of the Chinese whispers game.

Flux-inspired stores can mitigate the risks, as components can retrieve the data straight from a source of truth.

The Chinese whispers analogy displays how information distortion is greater the longer the chain is. This also leads us to a fair assumption that state containers are more valuable in larger apps.

Single source of truth

Having a piece of information stored in multiple parts of the app has its own share of risks. It creates opportunities for it to get out of sync.

A managed store solves that by providing a single location in which to store information. It can be described as a golden source of data.

Encapsulation

State containers will typically avoid exposing the state directly. For the simple purpose of protecting it from unexpected mutations.

For updates which are required, the store will expose a set of methods which will apply precisely the required changes to the data.

By exposing limited and controlled mutations, it reduces the number of potential unexpected and uncontrolled changes.

Accountability and traceability

When dealing with bugs caused by an unexpected or wrong mutation, finding the source of that mutation can quickly become a hassle. Every piece of code is a potential suspect.

Luckily, a state manager only allows changes through a limited set of entry points. This narrows down the list of suspects: either the mutator method itself, or whichever code called it.

Thanks

Many thanks to those who have suffered through the entirety of the article.

Quick disclaimer: everything written here is the product of my understanding, experience and opinions, and should by no means be considered an absolute source of truth.

In addition, I would love to hear your thoughts and comments on this topic.

If anyone wishes to contribute and suggest changes, the paper will be available on my github.