DEV Community: miniscruff

Changie - Auto mode and GitHub action

miniscruff — Sun, 05 Feb 2023 06:53:30 +0000

Auto Mode

Using Changie for changelog management has a lot of advantages, but one thing that has been missing is a feature that is used a lot by commit message based standards such as conventional commits which is. Automatic version bumping based on changes. That is, if I add a new feature specified by the feat prefix, conventional commit knows to bump the minor version. If I instead used the fix prefix, it knows to bump the patch version.

Changie now supports this as an optional feature by using changie batch auto or changie next auto and it works by looking at the kind configs for the unreleased changes.

When creating a new project, the changie init command will include the defaults below for auto values.

kinds:
  - label: Added
    auto: minor
  - label: Changed
    auto: major
  - label: Deprecated
    auto: minor
  - label: Removed
    auto: major
  - label: Fixed
    auto: patch
  - label: Security
    auto: patch

This feature allows you to pretty safely execute changie batch auto && changie merge whenever you want to release instead of checking what changes are included and what the next version should be. And because this is an automatic change, any CI/CD processes you have can now go from 1 input to 0.

GitHub Action

Another thing that can help with using Changie in your project is the new changie GitHub action which can be used to run changie commands directly from your GitHub action pipelines.

A good example of using the Changie action is in the action itself, which uses Changie for changelogs and itself to batch and merge new versions. Quite the recursive project.

Here is a snippet of the full workflow

- name: Batch changes
  uses: ./
  with:
    version: latest
    args: batch auto

- name: Merge changes
  uses: ./
  with:
    version: latest
    args: merge

The full workflow for this is to generate a pull request with an updated changelog by running batch and merge, we also use the latest version as part of the commit message and pull request summary. This is also very similar to a workflow changie uses for itself, however, changie just runs the equivalent go run main.go * commands rather then the changie action.

name: Generate release pull request

# empty workflow dispatch as we want it to be a manually run 
# action, but we have no arguments for it
on:
  workflow_dispatch: 

jobs:
  generate-pr:
    runs-on: ubuntu-20.04
    steps:
    - name: Checkout
      uses: actions/checkout@v3

    # any custom build commands you want to include goes here

    - name: Batch changes
      uses: miniscruff/changie-action@v1
      with:
        version: latest # latest is the default and can be left out
        args: batch auto

    - name: Merge changes
      uses: miniscruff/changie-action@v1
      with:
        args: merge

    - name: Get the latest version
      # id is used to reference our latest version
      # in the next step
      id: latest 
      uses: miniscruff/changie-action@v1
      with:
        args: latest

    - name: Create Pull Request
      uses: peter-evans/create-pull-request@v4
      with:
        title: Release ${{ steps.latest.outputs.output }}
        branch: release/${{ steps.latest.outputs.output }}
        commit-message: Release ${{ steps.latest.outputs.output }}

That is all for now. Reach me on twitter @miniScruffDev or by starting a discussion on GitHub.

Changie - Replacments and Choices

miniscruff — Mon, 28 Mar 2022 02:08:10 +0000

Replacements

Odds are, if you are working on a large project or you are part of a team you are going to use more than one language. You might run python for machine learning, react on the frontend, ruby on rails for the backend and some java spring services sprinkled in. This on its own is not a problem, as engineers we have many solutions for this such as docker or kubernetes.

These tools will all have slight variations on how you might need to prepare and deploy a release. One thing in common is supplying release notes for a shared changelog. For this reason it was important that Changie work across as many languages as possible. One way this is achieved is with the replacement configurations. This configuration allows changie to update files with the newly prepared version as part of the build process. It works very similarly to sed with go templates for the version values.

NodeJS

Lets run through some examples, for NodeJS projects you will include the project version in the package json file. To have Changie update this value when you batch your release notes you can use the config below ( also seen on the docs here )

replacements:
  - path: package.json
    find: '  "version": ".*",'
    replace: '  "version": "{{.VersionNoPrefix}}",'

Python

There are many ways projects define the versions in python projects so I can't go over all of them. But one common method used by fastAPI is to create a version attribute in either a __init__.py or __main__.py file at the root of your project. For example here is where the version is defined for FastAPI. This can be updated with a configuration similar to this:

replacements:
  - path: "fastapi/fastapi/__init__.py"
    find: '__version__ = ".*"'
    replace: '__version__ = "{{.VersionNoPrefix}}"'

Rust

The cargo toml file includes a version field so the replacement for that would look like:

replacements:
  - path: "cargo.toml"
    find: 'version = ".*"'
    replace: 'version = "{{.VersionNoPrefix}}"'

These are just a few examples, you can of course include multiple replacements and it should work for any language.

Choices

Changie will prompt the user for answers to two questions, if enabled anyway, when creating a new change fragment. These are kind and body. Kind is associated with the type of change such as added, fixed, removed, or deprecated. Kind configuration allows setting labels, headers and formats.

The second question is the body of the change. This to can be disabled globally or per kind. You may want to disable this for certain kinds of changes that require more specific prompts.

Custom choices can be configured to add additional prompts to provide additional information for each change fragment. These choices are added to a custom map that can be used in the change format.

A short example is the one from Changie itself that asks for an issue number and adds a link when formatting. Changie's .changie.yaml is basically the default configuration with the issue choice added.

changeFormat: '* [#{{.Custom.Issue}}](https://github.com/miniscruff/changie/issues/{{.Custom.Issue}}) {{.Body}}'
custom:
- key: Issue
  type: int
  minInt: 1

Another idea is to include a link to the author at the end.

# config yaml
custom:
- key: Author
  type: string
  minLength: 3
changeFormat: '* {{.Body}} fixed by [@{{.Custom.Author}}](https://github.com/{{.Custom.Author}})

Custom choices can also be used in the header and footer formats. Such as including authors in the footer.

custom:
- key: Author
  type: string
  minLength: 3
footerFormat: |
  ### Contributors
  {{- range (customs .Changes "Author" | uniq) }}
  * [{{.}}](https://github.com/{{.}})
  {{- end}}

That is all for now. Reach me on twitter @miniScruffDev or by starting a discussion on GitHub.

Changie - Automated Changelog Generation for Large Projects

miniscruff — Sat, 26 Mar 2022 21:05:51 +0000

Preleases

When working on large projects or projects that require a few extra checks before being considered stable it is common to have prerelease builds. They go by many names but most importantly they use semver's prerelease field to define them.

It is still important to share notes on the differences in each prerelease build to communicate what has changed but what do you do when the time comes for the final release?

A common method for this is to create prerelease notes for each build as they are made. Then, when the final version is ready, package all the prerelease changes into one final release. This is because the prerelease builds were really only for testing and once the final version is ready we just want to document what is in the new version.

Changie supports this workflow by moving change fragments to a separate directory when batching new versions. And then when the final version is ready, including that separate directory or directories.

Here is an example workflow. Lets say your project is preparing for a big upgrade in v1.5.0. This release brings a lot of nice features while maintaining backwards compatibility so you want to release a series of release candidates before the final one.

# add features for next release
changie new
# batch our features for this release candidate
changie batch minor --prerelease rc1 --move-dir v1.5
# optionally merge to your CHANGELOG.md if desired
changie merge
# repeat the above for as many candidates as your project needs
# then when the final is ready
changie batch minor --include v1.5 --remove-prereleases
# include remove-prereleases to remove the v1.5.0-rcX versions already released
changie merge

Options are available if you choose to keep prereleases around, move each prerelease into a new directory each or if you prefer to just chain releases you can use --keep with each build.

Changie batch docs will have all the information you need.

Metadata

In addition to prereleases semver supports build metadata to be included with your versions. This can be used for pretty much anything but a few examples are; operating system, date, time, git hash or any combination.

You can easily include build metadata by adding -m or --metadata to batch.

A small example would be to include the current date and time as well as the first 12 characters of the git hash with each release.

$ changie next minor \
    -m $(date +%Y%m%d) \
    -m $(git rev-parse --short=12 HEAD)
v1.7.0+20220326.4f48261c620e

Changie next will just output what the next version would be, it takes similar parameters as batch.

That is all for now. Reach me on twitter @miniScruffDev or by starting a discussion on GitHub.

Changie - Automated Changelog Generation for Any Project

miniscruff — Sun, 13 Mar 2022 20:40:19 +0000

Getting started experience with Changie.

It was over a year ago that I posted an article about my side project changie. That post was mostly a comparison of the file based approach compared to commit messages, this post is more about the Changie specific features.

The full changelog for Changie, generated by Changie can be viewed on the website or on GitHub.

Headers and Footers

A big improvement to Changie has been allowing users to add custom headers and footers in a few formats. With full support for templating you can do some cool stuff.

For all the details see the docs on headers and footers

A small example could be to show many updates happened for each kind.

headerFormat: |
  Updates:
  {{- range $kind := (kinds .Changes | uniq)}}
    {{- $changeCount := (kinds $.Changes | count $kind)}}
    {{- if gt $changeCount 0 }}
    * {{$kind}}: {{$changeCount}}
    {{- end}}
  {{- end}}

The end result would look something like:

## v0.1.0 - 2022-03-13
Update Counts:
  * Added: 2
  * Changed: 1
  * Deprecated: 1
  * Fixed: 3

### Added
* A
* B
### Changed
* C
### Deprecated
* D
### Fixed
* E
* F
* G

One team is using the custom footers to show any public contributors per pull request, check out the discussion.

A simpler version of showing all unique contributors from GitHub would look like this:

# config yaml
custom:
- key: Author
  type: string
  minLength: 3
footerFormat: |
  ### Contributors
  {{- range (customs .Changes "Author" | uniq) }}
  * [{{.}}](https://github.com/{{.}})
  {{- end}}

Currently you can see headers and footers using either a format option in the config, a file path option in the config or by passing an argument to batch.

Latest

When creating tooling for automation or release notes it can be quite useful at times to know what our current version is.
A good example of this is combining Changie with release automation such as GoReleaser as seen by this GitHub Workflow.

See the Latest command docs.

Bumping

Bumping can be used to increase the current version to the next version by semantic name instead of a new version. See the batch command docs.

# instead of
changie batch v1.4.1
# you can use
changie batch major
changie batch minor
changie batch patch

If you just want the output for the next version you can use next. See the next command docs.

Dry runs

When editing Changie configs, running a demo or maybe as part of CI logging, it can be useful to see what the output or changes would be without actually making those changes.
This is especially true for Changie as, by default, it will create and delete many files that could be tedious to get back.

To that end, any command that would write out to a file, edit a file or delete a file, you can add --dry-run to instead print to standard out.

changie new --dry-run
changie batch patch --dry-run
changie merge --dry-run

That is all for now. Reach me on twitter @miniScruffDev or by starting a discussion on GitHub.

Thanks for reading.

Get help automating your releases

miniscruff — Tue, 23 Feb 2021 08:17:30 +0000

Recently I posted an article about my side project Changie which automates changelog management. Currently, the only project using Changie is itself, which is kinda funny.

Changie is only one piece of release automation that, I think, every project should have. But, if you are new or just a little inexperienced with release processes this can be a little overwhelming. So, I plan on offering some of my spare time to help other projects automate releases, including Changelogs. Ideally of course using Changie, but if your project doesn't fit within Changie's scope then I understand.

Note that the release automation is separate from automated tests, linting, and build checks but those are still very important.

So if you have a project that has the following criteria you can reach me below, on Twitter @miniScruffDev, or as a discussion post on GitHub.

Project is open source
Project has been updated sort of recently, at least in the last few months
You would like to create or automate your changelog
You would like to automate your releases
The project is written in Go, Python, or Javascript/Typescript ( As I only currently have experience publishing on PyPI/NPM, and Go has no package repository )
You of course would need to use Changie

Not sure exactly how well this will go, maybe only a few people may be a lot so will see how it goes. Of course, if you want help but maybe don't fit all the requirements you can still ask.

How exactly I help could range from a simple pull request to private help, or a Zoom call, whatever fits best.

Changie - Automated Changelog Tool

miniscruff — Sat, 20 Feb 2021 22:57:02 +0000

If you are developing a library, tool, package, or virtually any software you probably make a lot of changes. With all these changes you will want to inform your users, how might you do that?

I will be going over as much information as I have about changelog methods and structures to compare my tool Changie with. That way you can come up with the best approach for your team, project, or organization.

Well, if you are building 'dev.to' you can publish Changelog posts describing all the new features directly. How else might you do it?

There are two things to consider here:

What format and method do we use for versions and changes
How we track and publish our changes

SemVer and Keep A Changelog

By far the most common method of versioning is semantic versioning. This is the preferred method if your project needs to keep some form of compatibility with previous versions. Alternatives are calver or my own hashver but for this article, I will be assuming semantic versioning.

The next question is how we format the changelog in a clear way. For that, the most common structure is Keep a Changelog. It is simple, clean, and well organized. There are other structures and creating your own is not too difficult so feel free to customize it a bit. The important part is that you have a cohesive structure and an easy-to-find place.

Tracking changes

When developing your features you will need to eventually include these in your changelog, how do you go about tracking all these before your release is ready?

Well, I have seen 3 different methods:

No tracking

Don't do any tracking and write your release notes when you release. The idea here is that... well ok not much of an idea really you just wait until you want to release then try and figure out all your changes from memory, maybe your completed issues or closed pull requests?

This tends to be the default as it is the "Do Nothing" approach. Of course, this often times translates to not having any changelog.

Commit Messages

Probably the most common option, or at least most readily available, is to pull your commit messages since the last release and package it all up. You have tools and formats such as conventional commits combined with standard version can auto-generate changelogs for you. NodeJS's changelog maker does the same thing in one package. GoReleaser has a built-in release notes tool that acts very similarly.

Using Files

The last method, and the method used by Changie, is to store "change files" in your repository while you are working on new features, bug fixes, or improvements. Then through some templating tool combining all these files into your CHANGELOG.md for users. Or at least something similar to that.

Examples include:

Pythons Blurb It generating the What's New pages
Gitlab's Changelog Entries which they explain why in the History section
Twisted's Town Crier is a generic tool

Changie

Changie is a new tool very similar to Town Crier and the other file-based solutions with the intent of being customizable enough to fit any project's needs. It is also released as a single binary using Go so it should be easy to install on any machine.

What makes Changie unique

In keeping with the agnostic approach Changie aims to remove any language, tool, or framework requirements for changelog management. Creating binary releases for all platforms makes it easy to install no matter what language or tool your project is in (might need to add more but this is the goal). Changie is not a project requirement and will not be included in any dependency file. It is also not required for CI/CD like GitHub actions or Gitlab CI. Although, it can be integrated with them quite well. The latest command can be used to output your latest version for release generation.

Ability to customize a lot of the formatting outputs, with more options to come if needed.

Changie uses a prompt-based CLI that can be extended with additional choices. This system also includes validation options to check things are proper. More validation options will be added later but this already reduces typos and bad inputs.

Do you reference your version in multiple places? Update them all during your release process using replacements which is basically just a find and replace option.

Git is unused and not a requirement, you could use any source control on any platform and Changie would act the same way.

All these options and features allow you to run two commands (batch+merge), then create a pull or merge request. The result of this commit is a release-ready point with a new changelog and versioned release notes. You could use GitHub releases, GitLab releases, or publish them on a blog.

Note: Two commands are used here instead of one to allow you to include extra information with each release such as upgrade notes, more in-depth descriptions, or other release information not tied to a specific change.

For example, Changie uses itself for its own Changelog management. You can view the resulting CHANGELOG, changes directory and the GitHub release action publishing GitHub releases.

Benefits of Files over Commits

Using files may seem a little strange to those who have used commit messages or just written up changelogs before so I would like to include a few advantages of using them.

Separate information for developers and users: Developers care about technical details but users don't. If you have to pull both from commit messages it will be hard to make it clear. This will not matter if your tool is for developers but even then, some details are only impactful for internal developers.
Typos: If you have a typo in a commit message it will be pulled in for your changelog. If you fix it in the generated changelog it will still be wrong in the commit message. Using a file allows you to update it if you need to. You could also just remove it entirely if the feature was later removed before the release.
Reviews: Using a file allows you to include changelog updates as a part of your pull requests. This allows you to get reviews on the final output, especially helpful to get managers or tech writers to comment.
Customization: Using commit messages rely on a rather strict input and output system. Customizing these can be difficult if possible at all. Conventional changelog spec can be found here but if you wanted to add a new field it is not possible.
Use Any Commit Style: Using Changie does not restrict you from defining some commit style like standard commit or anything your team likes. But these are for developers only and should not be generated for your end-users. It also allows you to write smaller more concrete commits knowing each of them won't be part of the changelog.

Thanks for reading, if you are interested in trying Changie the guide is a good place to start.

Changie is of course open-sourced on GitHub. Feel free to comment or reach out on GitHub.

Hidden TDD Benefit: Bookmarks

miniscruff — Mon, 17 Feb 2020 09:33:02 +0000

TDD is often mentioned for its benefits in code quality such as following DRY, YAGNI or other clean code standards. Today I want to talk about one overlooked benefit that has helped me countless times.

Working in an open office has a few benefits but many downsides as engineers. Tips such as pair programming or listening to music help a little but even then there are always distractions. In addition to distractions, there are always times in your workday when you need to stop working for some amount of time. We all have to eat at some point.

With the constant problem of starting and stopping at least a handful of times a day, how does TDD help?

Bookmarks

TDD offers one very powerful advantage, a bookmark. You see, TDD is split between 3 phases usually referred to as red, green, refactor. Each of these three states can be easily discovered by running your test suite. By making our feedback loop as small as possible it also reduces the amount of information we have to keep in our heads at once.

Now generally, TDD expects you to write your test just before it fails. This is so that you do not preemptively write code for a later feature. However, we can take notes on what tests we will probably want to write later. That is, a comment or a test case that has no code but a failing assertion. We can use the name of the method to know what we need to write when we get there. This acts sort of like chapter titles.

Before we begin we do have to do some setup work. Depending on your preferences and test runners you can choose between;

Writing empty test methods that fail
- Only recommended if you can stop your test runner on the first fail ( for python and pytest you can add the -x flag )
- If you can not stop on the first failure you will have to keep scrolling up to get the error logs and it's not fun
Writing notes in code or on paper for your next tests
- If using this method I like to write the method how it would look but just comment it out so I can pull it in later.

Note that I recommend configuring your test runner to re-run your suite on file change. For python I use pytest-watch, karma has a configuration for it, I believe jest does as well.

Take a break at any time

Now that I have a set of test cases written down I have a few benefits. The first is, until all these test cases are done I know exactly what I am doing. And at any point, I can take a break and come back and know exactly what I need to work on next.

This plays out in two ways depending on your choice of commented test case notes or failing empty test cases.

Failing empty test cases

This is my preferred approach.

We start by writing test methods with descriptive names and just a single failing assertion.

def test_missing_user_auth_raises_401():
    assert 0

An example that has a clear description but no code. We can write as many of these that we come up with ahead of time. Noting that we may change our mind later but that is fine.

Now, if we come back from a break and our tests fail because 0 is not true ( or the equivalent for your language ) then we know we are in the green or refactor phase and we can choose to refactor or write our test.

If we come back and our test is failing for any other reason. We know we are in the red phase and we need to add code to get our test to pass.

Finally, if all our tests pass it means we have finished all our existing test cases. At this point, we can probably make a pull request. ( or add docs and that good stuff )

Test comments

If you go the route of just writing comments the flow is similar but has a few differences.

If we come back from a break and our tests all pass then we are in the green or refactor phase and can pull the next comment out and write a test case.

If we come back and our test is failing, then we are in the red phase.

Finally, if our tests pass and we have no more comments we make that pull request.

With this, I have been able to work quite efficiently despite the many distractions of an open office.

Thanks for reading.

Introducing HashVer

miniscruff — Mon, 03 Feb 2020 22:06:30 +0000

I have been using a microservice like architecture at work for quite some time now ( about 2 years ). During this time I have mostly used semantic versioning for my builds. Using docker and a staging environment my workflow was as follows:

Create a feature branch and pull request
After reviews, it is merged into master
Jenkins then builds a new :stage docker image and deploys into staging
After some time passes and we are satisfied with the stage build, we then prepare the next release
This involves updating the CHANGELOG.md, at first it was manual but then I built a tool
Then bumping the internal version field
Creating a new PR for these changes and letting Jenkins redeploy stage.
Then manually running a second job, which retags the latest stage image as the semantic version number and updates production

This works out pretty well and is quite an improvement over what others on my team are doing ( do not get me started on that ). However, a few things have bugged me about all this.

A lot of steps for a new release
Each release usually only had one maybe two small changes and really didn't need that much overhead
When going from stage to prod, we rebuilt the image after we did our testing
Our staging environment wasn't being used much and thus our testing wasn't significant
Finally, the semantic version wasn't helpful in this case ( read more below )

Why not SemVer for services

Semantic versioning is by far the most popular and common versioning scheme out. It is very well documented over at https://semver.org and is used by countless systems such as NPM, PyPI, NuGet, etc. I recommend and use SemVer for most work, but for services, I do not.

The reason for this is SemVer aims to provide a means of safety, that is with each update you know if something will break or if its just bug fixes and is a safe upgrade. It aims to communicate a level of compatibility with other versions.

So if you are using version 1.2.0 and version 1.3.2 is the latest, you know the versions are compatible and are generally safe to upgrade. If you are using 1.2.1 and the latest is 2.1.0 you know there is at least something that may be incompatible and you will need to make changes on your end to resolve it.

But when you are working on a service presented straight to users this compatibility is largely unhelpful. A version change does not help most, if not all, users. If a new feature is added or major change is happening, you would want a large announcement to go along with it anyway. Additionally, if you merge and deploy often this extra effort of coming up with a version and updating the changelog is tedious.

What does versioning do for you?

It is very common for sites and services to just not use any versioning at all. For example, I do not think dev.to has an explicit version number (at least, I couldn't find it anywhere). This is not really a problem, I mean, if your favorite sites did have a version would that help you as a user? No, probably not.

However, a version change achieves one big thing. It marks a new release. Think about a site you use frequently ( well, one that is also updated frequently ) how are you informed as a user of new changes? Do you get an email, notification, blog post, nothing?

See versions tie our application at a certain time with the capabilities it had. When a new version is released, there are more, less or better capabilities with it.

Hash Versioning

Version numbers for constantly updating services or sites are largely irrelevant but having some version number or string for every release allows us to reference old builds, see changes or diagnose new problems. ( A nice sanity check to make sure that production bug is actually a bug or if the service was never deployed ). So, I created hashver which aims to build a generic version based on the date and git hash.

These two pieces of information allow you to know approximately when the build was made which helps find stale builds and can signal the frequency of updates. The hash can be used to find the source. No need to git tag every release.

Note that HashVer is not anything too new, I have heard or seen instances where similar versions are used especially for nightly builds. But by writing up a formal definition it can be standardized and shared.

Cool now what

Okay, so you have a version number attached to each deployment, now what?

Well, good point, this version number doesn't by itself provide any benefit to our users but we have now automated it. You no longer need to choose or guess your version numbers, what else can we automate.

Your changelog.

What about building our changelog during our build/deploy process. Include this in your final build or referenced somewhere for your users to see when and what was added or changed. You can use many tools but I created hash version for python, town crier is also popular. GitLab has built changelog manager. Python uses blurb for its official whats new page.

What else?

Automated announcements for big updates
Blog posts integrated into the changelog
In-app notification on updates

Once you have a place for automating release artifacts you can add many more.

Why go through all this effort?

By including news and updates directly in your application, it allows users to take advantage of new features. How many times have you been using an application and discovered a cool feature and asked yourself "wow, this is cool when did they add this?". What about spending 3 months on a new awesome feature only to have no one use it cause it was hidden? Ever get asked about a new feature request and responded with "Oh, that is already available, and been there for 6 months?".

Version changes mark a new release. This point is your time to add as much metadata as you can in order to communicate this new release to your users.

Okay you convinced me, how can I do this?

First, start tracking all your updates that affect the end-user. They generally do not care if you fixed linting issues or switched from PostgreSQL to MySQL. But they do want to know if markdown tables were added.

Second, automate everything. Version changes, news generation, everything. If it's not automated, it will fall behind. And we plan on making lots of changes so this has to be lean.

Finally, provide all this to your users somehow. I like to provide a link to my changelog down in the footer, it fits for my circumstances, but you do you.

Changelog updates are just one part of what goes into each release, hash version aims to provide a foundation of what steps you should, could or may take in each microrelease. ( Microservices need microreleases just saying )

Thanks for reading.

How I Split Work: Recap

miniscruff — Fri, 17 Jan 2020 03:25:31 +0000

First off, thank you to everyone who has read my posts this will be the last one of the series. Today I will be recapping the series into a much smaller set of notes so you can bookmark this page for later.

Pitch
1. Elevator pitch or more of user features and experiences.
2. Enough to sell you on the idea
3. Could come from anyone
Cut
1. Take the pitch and cut out fluff, emotion, examples or unnecessary details
2. Technical details are also cut and can be saved for the very end
3. We end with a bullet point list of requirements
Merge
1. Combine any bullet points that are very similar and can be handled together
Abstract
1. Anything too specific can be abstracted up a level
2. We end with a clean set of requirements
Detail your end results
1. Blurb every idea you have
2. You may need to trim down some ideas to fit your timeline, but I like to keep them all somewhere for later
3. Check each idea to make sure it is viable and even possible
Detail how users start the experience
1. Match your end results and requirements to what you will need
Draw it out
1. Take the start and end to draw out a graph leaving a gap in the middle
2. Fill in the middle, lining up the start and end parts with the requirements
Break down
1. Take any abstract, high-level node and add details
2. Split any merged requirements into separate nodes
3. Make note of any edge cases and abort conditions
Review
1. Get someone else to review your chart, preferably someone who wasn't part of the process
Cleanup the chart
1. Optional: If you want to clean up your graph and maybe upload it somewhere
Order
1. Start with closing the start > finish loop
2. Then get the program to work correctly ( sometimes this is done already )
3. Then handle any skipped edge cases, usually saving exceptions for last

If at any point you feel things are not lining up or feels a little off, maybe even too big. Stop and go back a step or two and try again. More art than science here, quickly doing one or two iterations until you are happy is better than being far off later.

Now you can start working, follow the style you prefer. I recommend TDD ( test-driven development ) or XP ( extreme programming ).

That is it, thank you for reading this series.

How I Split Work: Review, Cleanup, and Order

miniscruff — Thu, 16 Jan 2020 05:43:55 +0000

As with any design you should always get your ideas reviewed by at least one other person. They will help catch things you missed or have incorrect. For this example, I will illustrate this point by mentioning we need to check if there are any available seats before selling a ticket.

Cleanup

Now that we have our review complete, lets clean up this flow chart. This may or may not be necessary depending on how clean it was the first time.

I did not do such a great job the first time so I redid the flow chart, a quick sketch by hand is more than enough so do not think you need to spend an hour or anything on this.

Also, I just pick random shapes for things while trying to be consistent. If you know UML and like it, feel free to use that.

Order

Great we have a full flow chart from start to finish of what our product should do. Now what? Finding a reasonable order to work on the items in. The goal here is to do as little work, measured in time not count so big complicated stuff last, as possible in order to get our program to run with a result. The trick here is that we are ok with that result being incorrect as long as it completes.

An example is skipping out on the sales tax, sure our program won't yield the correct expected results, but it ran and completed with something. We can manually calculate what it should be for now. Or we can just have a failing test, personal preference here.

After we have our program running, we then want to fix any accuracy errors it may have.

Then to round it off, handle all the possible edge cases we know of.

Also, there will be many good answers to how you order things. So if what you came up with is different, that is probably fine. I will explain why I put things in the order I did as well.

We start with finding the price of a ticket, however, it does not need to be accurate yet. We can simply return any number here as long as it's done in some sort of function or class. We will want to modify this later on without affecting other pieces.
Once we have a price, we can calculate the total.
The first step of that is summing up all our tickets. We can make an array of our thing from before to sum it all up.
We can then calculate the change based on this total and our input cash amount. It will be incorrect with missing sales tax but that's fine for now.
After all that, we can now complete the flow and run our program from start to finish.
Now that we have it running we can fix the issue with our accuracy which comes from missing our sales tax. So let's do that next.
We have this working for a single ticket, lets now run this over a list of tickets.
Next, let's fix up our price math to return the real value of our tickets in all cases.
Finally, we end our feature set with calculating our discounts.
End our work by checking for all our edge cases making sure if anything goes wrong we abort with no tickets created.

That is it, you can now start programming. With step by step tasks like this TDD is a great candidate to follow.

Thank you for reading.

How I Split Work: Add all the cases

miniscruff — Wed, 15 Jan 2020 04:23:25 +0000

Now that we have a rough outline of what sort of flow we have we want to fill in some of the gaps. At this point, we have to go back through all of our notes to make sure we do not forget anything. It is basically now or never, although not really but we can pretend.

So anything in our flow chart that is vague or is many smaller pieces we will now break down. Once we break it down we will then handle any bad edge cases and take note of them. We have not decided what will happen for these but we can mark them.

Break it down

Check to see if the ticket is available

There is nothing related to this block that we need to break down, we will be going over this in the next part.

Find the cost of the ticket

This was mentioned during the pitch that we have ignored since. Now we can add those details back.

Cheapest tickets during the week before 6 pm
Middle tickets during the week after 6 or weekends before 4
Expensive tickets weekends after 4

Note: There are 6 ( 3 ticket prices for child and adult tickets ) values here we do not have, but that is fine. In fact, we could probably pull out the times as parameters in case they end up changing.

Apply all discounts

This one we got back during the pitch as well, just a few different types of discounts. We do not yet know how much or how they combine, we will have to get that answered later ( hint hint ).

Military discounts
Senior discounts
Special promotions

Sum all tickets for a total

While going through this process you remember that we need to apply a sales tax, so we can add that now.

Add X% sales tax to subtotal for a total

Throw your hands up

Now that we have some more details on our blocks, lets now focus on cases that might cause the order to be aborted. We do not know what to do about it yet, but we can mark it down.

Check to see if the ticket is available

Is there a movie playing at the requested time?
Are we trying to buy a child ticket during adult Monday?

Sum all tickets for a total

What if the customer did not give us enough money?

Print out tickets / receipt

We are going to assume that the printer works just fine, so no edge cases here. In practice, we would want to catch failures here as well but to keep this a little smaller we will ignore it.

Recap

That is it, we should have enough details here to present a pretty well thought out plan to our lead or clients.

The flow chart is a bit squirrely at this point which is half cause I do not use draw.io much and half cause we just added a bunch more to our rough draft. This is expected, we will redo it a little later to be cleaner.

You should see some of my flow charts, 3 or 4 iterations of a rough draft on one page, it gets really bad. For this reason, I like to use a small binder instead of a traditional notebook. It lets me rearrange my pages at will and I can swap between grid and lined pages.

Thanks for reading.

How I Split Work: Draw it out

miniscruff — Sun, 12 Jan 2020 19:13:41 +0000

Through the first four articles, we have achieved some really great results.
We were able to take an elevator pitch, filter just the important parts, analyze the end results and also the beginning.

At this point, we can take our notes and pitch it to our project lead, product owner or a similar role at our company. Or, we can take this back to our users and get their thoughts. For demo purposes, I will be skipping this review step but this would be the first time you could do one. Even if you do not review it with another group, it is still good to take your notes and just say them out loud. Rubber duckies work great here.

I prefer to do all drawing with pen and paper, but I will be using draw.io to share.

Our goal for this stage is to take what we have written down so far in bullet points and map it to a flow chart. We will be doing this twice, first for the user experience side and second what our internals need to be for that to work.

For reference our existing notes consist of the following:

Beginning
1. Requested tickets for the customer
2. Amount of cash they are paying with
Middle
1. Accept multiple tickets for any number of movies at once
2. Allow discounts and promotions
3. Only accept cash
4. Tickets will have varying costs
5. No child tickets sold on the first Monday
End
1. I should receive one ticket for each person
2. My ticket should ...
3. I should be given a printed receipt of the transaction
4. My receipt should ...
5. I should get the change back with my ticket

As with all our previous steps I do this in two stages. First, I write out the beginning and the end. Then, I fill in the gaps with the middle pieces.

Outer Rim

To start with we will be doing just the beginning and end stages with a magic "stuff" in the middle. The goal here is to force us to fill in that gap such that it makes logical sense and flows. If we were to start with the middle and work outwards we might assume we are given more than we are or that the end result is easier than we want.

Note: If you know UML you can use it here, I do not and just pick shapes that I like for different nodes. Our flow chart will never be so intense we need most of what UML offers. If you ever feel you need to do full UML you probably just want to split your entire task.

Plug the hole

As we do our next stage we want to get as many of our supported features as possible but only from a high-level description. We do not want to go into technical details here or try and explain every conditional situation. At the end of this, we can have another review with users or project leads all while speaking our native language.

The longer we can go without writing code the better. This might sound "unagile" or "waterfally" as we are spending so much time upfront but this should be cleared up later. ( If not, ask in the comments )

Explanation

If you notice I did not explicitly mention how to find the cost of the tickets or for what reasons a ticket would be unavailable. At this moment, I am choosing to hold off on those details. Because at this stage all that would do is cloud the flow and cause it to balloon in time required. This is all meant to be done quickly. We can get a pretty good understanding of flow with simple notes like this more than a full book.

We are also only focusing on the path that assumes all conditions are valid and no edge cases are hit. That is, we do not handle if the customer does not give us enough money or the ticket is not available. We will be handling these later.

Thank you for reading.