docs: rewrite README to align with the deessejs org template - #387
Merged
Conversation
added 5 commits
August 4, 2026 12:49
Adapt the README structure used across the deessejs org to the shape of @deessejs/fp (a focused TypeScript library, not a SaaS app). Adapted sections: - Banner: dropped (no banner image). Kept the title + tagline + badges layout. - What's included: replaced the SaaS layers table with the @deessejs/fp public API surface (Result, Maybe, Try, Unit, functional utils, async utils, predicates, collection types, generator composition, @deessejs/errors integration). - Why this stack: simplified to ESM-only, zero runtime deps, TS 6 first-class, pnpm lockfile-clean, Vitest. - Quick start: install + usage snippet + engine compatibility table. - Available commands: workspace + per-package tables for @deessejs/fp and apps/web. - Environment variables: replaced with a 'Compatibility' section listing peer deps and engines (lib has no env vars). - Project structure: reflowed around packages/fp + apps/web (2 workspaces) instead of the SaaS monorepo. - Deployment: replaced with 'Publishing' that documents the Changesets + OIDC pipeline (with a link to docs/engineering/plans/release-pipeline.md). - Customization: replaced with notes on the public API surface and how to consume the lib. - Architecture notes: ESM-only, strict types, composition over inheritance, zero-runtime abstractions, smoke-tested build, @deessejs/errors opt-in. - Contributing: running lint/test before PR + adding a changeset for user-facing changes + updating docs/internal/product/README.md. Dropped sections (not applicable to a library): - Deploy with Vercel / GitHub Codespaces buttons - Environment variables table (lib has none) - Deployment / Per-app mapping (no production URL) - Multi-tenant / single-tenant customization notes Sibling project callout: - Adds a top-of-file callout for @deessejs/errors as the natural pairing library, matching the org convention of cross-referencing sibling packages. No code changes. Documentation only.
Two follow-ups on the README rewrite: - Remove the banner placeholder note (no banner image applies to this repo, but the explanatory note is unneeded once the title and tagline are in place). - Link to https://github.com/deessejs/errors at every mention of '@deessejs/errors' in the body. The previous version had plain-text mentions in the compatibility table, the engine bullet, the integration test bullet, and the install block; these are now Markdown links (or in-block comments for the bash example) so readers can navigate to the sibling repo.
Adds a third callout after 'Sibling projects' that signals production usage of @deessejs/fp at deessejs.com — every error path and nullable value in production goes through this library and its sibling @deessejs/errors. This is a credibility signal for npm visitors: the library is not a side project, it is the foundation the deessejs app runs on. Placement: in the existing callout block at the top of the README, between 'Sibling projects' and the section divider.
Per reviewer feedback: merge the 'Sibling projects' and 'Used internally' callouts into one paragraph on a single line. The 'Sibling projects' portion now references @deessejs/fp's own repo via a proper Markdown link (it was missing one). 'Used internally at deessejs.com' is now a single bold sentence appended to the same blockquote, not a separate callout. Net effect: less visual noise at the top of the README, same information delivered.
Unifies the support address across the repo to support@deessejs.com: - README.md: 'hello@nesalia.com' -> 'support@deessejs.com' - .github/SECURITY.md: 'security@nesalia.com' -> 'support@deessejs.com' Decided against keeping a separate security@... address; the single support@... inbox routes security reports to the right team (as documented in SECURITY.md). No code changes. Documentation only.
3 tasks
martyy-code
pushed a commit
that referenced
this pull request
Aug 4, 2026
Patch bump to push the restructured README + enriched package metadata (keywords, bugs, peerDependenciesMeta) to npm. No code change. The version bump is needed because the release pipeline is PR-merge-driven and the prior merges #387 and #388 did not trigger it (their changesets were empty). The hotfix tag path is the fallback for this case.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
README.mdto follow the deessejs organization template, adapted for a focused TypeScript library (the repo is a monorepo with two workspaces:packages/fpandapps/web, not a multi-app SaaS).Why
The previous README was minimal and used a generic "TypeScript package template" layout. Aligning with the deessejs organization template:
@deessejs/fpdiscoverable as part of the same family as@deessejs/errors,deessejs/fp, and the main app.Result,Maybe,Try, etc.) up front, instead of burying it in a code block under "Getting Started".@deessejs/errors.Changes
The new README follows the same section ordering as the deessejs org template (title, tagline, badges, sibling-project callout, What's included, Why this stack, Quick start, Available commands, Project structure, Publishing, Architecture notes, Contributing, License, Support).
Adaptations specific to a library:
Sections unchanged in shape:
@deessejs/errors).Test plan
pnpm turbo type-checkpasses.pnpm turbo lintpasses.README.mdhas 225 lines, no broken links verified visually).Risk
None. Documentation only. No code change.
Rollback
Revert the merge commit. The previous README is preserved in git history.
🤖 Generated with Claude Code