V1 Requirements

We have some BIG proposals outstanding for Porter that would push off a v1.0 if we tried to get all of them (and their breaking changes) in before cutting a v1. Since this could take the next year or more, we want to stabilize the current fucntionality and ship a v1 instead.

A v1 would not include these recent propoals:

• Mixin Versioning. We may break this up and put some in v1.0, but reserve the larger changes which are related to mixins as bundles for later.
• Mixins as Bundles
• Advanced Dependencies
• Labels and Namespaces
• Log Sources and Levels

These large features would all be shipped under feature flags. We would avoid a hard cutover of the code to a long running v2 branch as much as possible. After they are all in-place, we can start bikeshedding a v2.

Features that do not include breaking changes would be shipped as minor releases on v1.

After we cut a v1, people would have a stable version of Porter (v1.x) without worrying about breaking changes. We are only guaranteeing compatibility in v1.x for the runtime, porter configuration (config.toml/porter.yaml) and CLI API. The underlying Porter library is not included and will change.

When people move from v1 to v2 (or use a feature flag), it will require changes to their config, porter.yaml, runtime behavior expectations and/or the CLI API.

Since we are looking at multiple features that are interrelated, we may want to enabling/disabling new features by simply rolling them under an –experimental flag. More fine grain flag config would be reserved for the config file/env vars but not exposed as flags. Some features may not work unless you turn on all the appropriate feature flags, e.g. dependencies would need the ADVANCED_DEPENDENCIES feature flag and the NAMESPACES_LABELS feature flag.

(vdice: 2 notes: 1. These flags could live in Porter's config, right? 2. We would track any experimental features in the bundle that is built with flags, via the standard porter custom section (or other?))

What needs to be v1.0?

(Existing 1.0 milestone: https://github.com/getporter/porter/milestone/16)

• Sev 1 bugs (🚨🍫 and higher)
• Remove deprecated yaml fields. We have fields right now that have been marked as deprecated (e.g. tag), those should be removed in the v1 release. https://github.com/getporter/porter/issues/1408
• Do not install mixins/plugins by default. https://github.com/getporter/porter/issues/1192
  • Breaking change unrelated to the proposals above.
  • Fixes problems with who gets installed by default (only exec), and installation time, and upgrading just porter without messing up which version of a mixin is installed.
• Detect and prevent reusing installation names. https://github.com/getporter/porter/issues/1177
  • We care because this can seriously mess up an existing installation and it's easy enough to mess up.
• Move the generated Dockerfile to .cnab/Dockerfile https://github.com/getporter/porter/issues/1162
  • Maybe breaking change unrelated to proposals above.
  • Helps avoid problems accidentally overwriting existing Dockerfile that didn't belong to Porter.
• Any file format changes that we can easily put into v1 that would ensure that the bundle would still work after we implemented v2.
  • Specifying the version of porter targeted by a porter.yaml https://github.com/getporter/porter/issues/1566
  • Tweaks to the dependencies yaml schema to allow the necesary placeholders for our v2 plans. Such as moving the list of dependencies under a required section. https://github.com/getporter/porter/issues/1570
  • The goal is not to implement things now, but since we know the breaking file format changes we want to make, lets leave room for them so that the current behavior in v1 matches up with the default behavior in v2 without having to change the porter.yaml. If we can avoid a "porter.yaml migration", let's do so.
• Templating syntax changes, e.g. using a custom yaml node to denote templating. (NEED PROPOSAL)
  • I haven't proposed this yet but it would mean that yaml nodes that rely on templating would use mykey: !t {{ bundle.parameters.foo }}. This fixes the core problem outlined in https://github.com/getporter/porter/issues/316 where we can't represent an integer or boolean value only strings when templating is used.
  • We can do just a small part of the desired changes for templating, just to make sure the yaml schema aligns after we implement the rest of the feature.
• Figure out how we support tags in image map. Document it and make sure it works. https://github.com/getporter/porter/issues/1357
  • Add link to cnab to oci issue
  • May be a lower priority but it does impact the porter.yaml schema
  • one option is to remove tag, and add it back later if we support it properly
• Publish to ghcr.io, get off of docker hub. this is a breaking change for people's scripts.
  • Ralph: github is funded to support public packages 💰
  • Jennifer: it's free for public packages, paid for private

Usability issues for v1

We can address pain points and usability issues

• Make mixin descriptions optional in porter.yaml
• Allow a leading v prefix when specifying the bundle version, e.g porter build --version v1.0.0. We can always write out what's required in the spec to the bundle.json. No need to be strict in the porter.yaml/cli. https://github.com/getporter/porter/issues/1432
• Reduce build time for small bundle changes
  • Adding buildkit support (I have this implemented in a branch), would be a big speed improvement for builds while people wait for the other propoals. LINK TO BRANCH
  • understand minimum daemon version
  • understand if buildkit has a stable release yet or not
  • buildkit doesn't support building windows images
  • May need to hide behind config or –experimental
• Rename "table" format to plaintext https://github.com/getporter/porter/issues/1491
• Separating the current working directory from porter build. Do what docker build does with a build context and dockerfile. (vdice: perhaps https://github.com/getporter/porter/issues/1498 and https://github.com/getporter/porter/pull/1515 are applicable here… 1403 appears to be around allowing the user to specify the working dir for a step, relative to the mixin execution) https://github.com/getporter/porter/issues/1403
• Be consistent with using maps or arrays when there is a unique value required. https://github.com/getporter/porter/issues/159
• Change dependencies templating from bundle.dependencies.* to installation.dependencies.* and make more information available from the runtime (i.e. the installation name of a dependency)

What could be in v1?

• Change the mixin declaration format to allow for specifying a version
• Install mixins if they aren't present. But don't do a cache. This much logic would work fine with a new implementation of mixins as bundles without reworking.
  • Yes this means that if you have two bundles with different versions of a mixin, that will cause the installed version of a mixin to waffle (and incure additional bandwidth).
• Sweep for breaking changes in the CLI API that we wanted to do before v1. If we can group together breaking chnages that would be great. These aren't features so much as making flags consistent.

What is NOT in v1

• Making our library API backwards compatible. We have outstanding changes that we want to make. For now, we version based on the user facing functionality of porter, not our exposed GO api.