Document Status: Accepted
Living document, this can still change

projen 1.0

Projen is in major version zero 0.x and has been for over three years now. It's time for projen to grow up!

In order to do this responsibly, a few things must still be implemented. This list of priorities has been consulted by the community as an RFC. The list is categorized in two groups. The Must Haves are defined as the essential tasks needing completion before we consider moving to GA. The Should Have items are considered high priority goals, with their implementation status to be assessed once we are ready for GA. But ultimately they won't be blocking a release.

Contributions for any other features are still welcome! However if you are invested in a GA release for projen, consider directing your efforts to the priorities as define here.

Must Have

• Release & Versioning Strategy Define and document how we are going to do this past GA, and how we are going to deal with future breaking changes. @mrgrain
  😎 Why: Even with completion of the Must Haves, projen will still require breaking changes. Having a predictable release strategy will enable customer trust.
  🎨 Prior Art: Semver as we currently use it; Node.js with a predictable schedule, maintaining an LTS and unstable version

• Rearchitect projen to use constructs framework #1763 @mrgrain
  😎 Why: Fundamental change in approach, needed so we can slowly start migrating existing similar features to use constructs
  🎨 Prior Art: feat: Projects and Components are Constructs #2974 [WIP] feat!: migrate to constructs #1671

• Decouple Project from GitHub #1761
  😎 Why: Reality is that not everyone uses GitHub. The hard dependency currently leads down a path of not abstracting features enough
  🎨 Prior Art: feat!: refactor Project into StandardProject #1883

• New documentation page chore: new docusaurus-based documentation site #3244 @mbonig
  This should be a component itself, but we can probably drop this if needed. Good candidates for doc frameworks are Docusaurus and mkdocs.
  😎 Why: Current docs are horrible to use
  🎨 Prior Art: chore(docs): Moved entire documentation to mkdocs  #2340

• Code cleanup tasks
  😎 Why: Start 1.0 with a clean-ish slate. These are generally straightforward to do, but might be a bit of tedious work. Likely won't go into a 0.x release, but part of the GAing process.

  • Remove all currently deprecated features
  • Fixing exports #2977

Should Have

• Framework for interactive prompts in CLI
  😎 Why: Laying the foundation for code-level framework will enable future use-cases; prompting for missing input greatly improves the UX for new users
  🎨 Prior Art: feat(new): interactive prompt for missing information on project creation #2975

• Support multiple workflow engines: Gitlab #2438 GitLab support for all built-in workflows
  😎 Why: As an outcome of removing the hard GitHub dependency, we should be able to support another implementation. However having a contract will at least allow users to implement this themselves

• Built-in TaskRunner improvements Use tasks dependency model, rather than imperative instructions
  😎 Why: Currently sub-tasks are added as imperative instructions to tasks, making it difficult to optimize task execution and progress to a certain stage. For example pre-compile tasks are currently only run as part of build.
  🙅🏻 Why not: However the current system appears to be working well enough for most scenarios.

• 💬 RFC: Task runner contract (pluggable task runners) #2051 (Includes a new Task dependency model - dependsOn instead imperative - and metadata for caching)
  😎 Why: This will open projen up to be more generic and integrated better with the outside world. The challenge is similar realm to a generic Workflows Engine.
  🙅🏻 Why not: Ultimately it doesn't appear to be as much as a blocker compared to Workflows, and it is at least possible to work around given that tasks can be changed. If we can only have one of the two, I'd pick Workflows over Tasks.
  🎨 Prior Art: [WIP] feat: custom task-runtimes #2468

• Feature & Configuration injection system
  😎 Why: Currently projen components are inherently closed. Once you use a component, you are forced to opt-in to all of it. This stems from the desire to have everything ready at constructions time and to enable a declarative option. However it doesn't have to be this way. We could take a Project and layer features on top of it, with component declaring their dependencies as needed, using sensible defaults or errors as appropriate.
  Some constructs have certain properties that can be set at construction time whilst others only support certain configuration via methods and some use a combination of both. We should ensure all 1st party components follow a standardized format (and document it!) to prevent users from having to actually read the projen code to figure out how to change a certain setting. My preference is to favour methods to change behaviours and use constructors as a quick way to "inject" new components i.e: constructor of a project would have some mechanism to enable/disable/inject components whilst a getEsLint() would return the component with a bunch of methods to change settings.
  🙅🏻 Why not: This is super undefined yet.

• 💬 RFC: Break up projen into several packages #2042
  😎 Why: This is probably the future.
  🙅🏻 Why not: There is no pressing need. It might also be easier to start breaking out packages once we are GA.

• Windows support, amongst others: windows: running tasks for projen development on Windows #3384 @gmeligio
  😎 Why: projen should have had this from the beginning.
  🙅🏻 Why not: Needs an owner who cares about projen and Windows, i.e. is a user of projen on Windows.

The Good, the Bad and the Ugly

All must haves already have some sort of experimental implementation. Some are further ahead than others. The biggest question-mark for me at the moment is removing the GitHub dependency.

Not all nice to haves are well-defined at the moment; we need to do some more requirements gathering there. Unfortunately many of them are also lacking a starting implementation. Some of the bigger items (e.g. Gitlab & Windows) are very unrelated to my day job, making it unlikely for me to spend much time on them.