Archives: Documents

Purpose

Enable developers to discover, authenticate, install, and safely use internal packages (shared libraries, SDKs, UI kits) across projects—without security or versioning issues.

Scope

• Applies to all projects using private registries or internal repos.
• Covers discovery → access/auth → install → update → troubleshooting → deprecation/migration.
• Tech-agnostic with examples for Node (npm/yarn/pnpm), Python (pip/Poetry), Java (Maven/Gradle), iOS (CocoaPods/SPM), Flutter (pub).

Objectives

• Standardize how internal packages are consumed.
• Ensure secure access (tokens, least-privilege).
• Reduce breakage via semantic versioning & pinning.
• Create a clear path for updates and deprecations.

Step-by-Step Usage

Step 1 — Discover the right package

1. Open the Internal Package Catalog (Notion/Confluence page or Nexus/Artifactory index).
2. Filter by language → capability → status (stable/experimental/deprecated).
3. Read the README & CHANGELOG for install instructions and breaking changes.
4. Confirm compatibility matrix (runtime versions, platform, frameworks).

If the package is missing, submit a New Package Request (template at the end).

Step 2 — Get access (one-time)

A. Obtain credentials

• Request scoped access via “Access Request & Tool Provisioning Workflow” (EPIC 1 – Doc 7).
• Receive token via the secrets manager (never via chat/email).

B. Configure your client

Node (npm/yarn/pnpm)

Create/update ~/.npmrc (user-level) or use project-level .npmrc:

# Example for GitHub Packages
@our-scope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}always-auth=true

Python (pip/Poetry)

Create/update ~/.pip/pip.conf (Windows: %APPDATA%\pip\pip.ini) or project pip.conf:

[global]index-url = https://<user>:${PIP_TOKEN}@pypi.our-internal.com/simple

Poetry:

# pyproject.toml[[tool.poetry.source]]name = "internal"url = "https://pypi.our-internal.com/simple"priority = "primary"

Java (Maven/Gradle)

Maven ~/.m2/settings.xml:

<servers>
  <server>
    <id>internal</id>
    <username>${env.ART_USER}</username>
    <password>${env.ART_TOKEN}</password>
  </server>
</servers>

pom.xml:

<repositories>
  <repository>
    <id>internal</id>
    <url>https://maven.our-internal.com/repository/releases</url>
  </repository>
</repositories>

iOS (CocoaPods / SPM)

CocoaPods ~/.netrc or keychain credentials; Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://git.our-internal.com/ios-specs.git'

SPM: Add internal Git URL in Xcode → Package Dependencies (use SSH).

Flutter (pub)

version: ^1.2.0

Security: Store tokens in env vars (e.g., NPM_TOKEN, ART_TOKEN) injected by your shell/profile or direnv—never commit to VCS.

Step 3 — Install & pin versions

Node

npm i @our-scope/feature-lib@^2.3.0
# or
yarn add @our-scope/feature-lib@~2.3.4

• Use ^ to accept minor & patch updates, ~ for patch-only, or exact for strict pinning (critical paths).

Python

pip install our-sdk==1.4.2
# Poetry
poetry add our-sdk@^1.4

Java

<dependency>
  <groupId>com.our</groupId>
  <artifactId>core-sdk</artifactId>
  <version>1.5.3</version>
</dependency>

iOS

pod 'OurSDK', '~> 1.4'# or SPM exact/range in Xcode UI

our_sdk: ^1.4.0

Governance & Standards

Versioning & Stability

• All internal packages must use SemVer: MAJOR.MINOR.PATCH.
• Breaking changes → bump MAJOR and provide migration notes.
• Consumers should pin (~) or lock (lockfile) for deterministic builds.

Security & Access

• Tokens are scoped (read-only for consumers).
• Tokens live in vault and are injected via CI or local secrets; no plaintext in repos.
• Remove access when a developer rolls off the project (EPIC 7 – Security).

Quality Signals (before adoption)

• Package must have: README, CHANGELOG, LICENSE (internal), tests ≥ 70% cov, CI status badge, semantic-release or documented release process.

Deprecation Policy

• Mark as Deprecated in Catalog with EOL date and migration path.
• Provide a compat layer or codemod where feasible.
• Communicate via release notes + #dev-announcements.

Troubleshooting (Quick Reference)

Templates & Snippets

1) .npmrc (project–level)

@our-scope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}always-auth=true

2) pip.conf (project-level)

[global]index-url = https://<user>:${PIP_TOKEN}@pypi.our-internal.com/simple
timeout = 60

3) CHANGELOG format (keepachangelog style)

## [2.3.0] - 2025-08-01### Added- New AuthClient.refreshToken()

### Fixed- Retry logic for 429

### Breaking- Removed deprecated `AuthClient.legacyLogin()`  - Migrate to `AuthClient.login(email, otp)`

4) Deprecation Notice (maintainer → consumers)

**Package**: @our-scope/logger
**Status**: DEPRECATED
**EOL**: 2025-12-31
**Replacement**: @our-scope/telemetry
**Migration**:
1) Replace imports
2) Update config key `logger.level` → `telemetry.logLevel`
3) Remove manual batching; built-in exporter enabled by default

5) New Package Request (submit in portal)

Do’s & Don’ts

Do’s

• Use scoped tokens and project-level config where possible.
• Pin or lock versions for deterministic builds.
• Read CHANGELOG before updates; test migrations on a branch.
• Log issues with repro, logs, and env.

Don’ts

• Don’t commit tokens or .env to VCS.
• Don’t auto-upgrade majors in CI.
• Don’t publish internal code to public registries.
• Don’t fork & drift—contribute upstream to the internal package.

Purpose

To provide a standardized guide for setting up local mobile app environments, ensuring developers can build, run, and debug apps consistently across machines (iOS + Android).

Scope

• Applies to all mobile projects (React Native, Flutter, Native Android/iOS).
• Used by Mobile Developers, Full-Stack Developers, and QA Mobile Testers.
• Covers toolchain setup, project configuration, and environment verification.

Objectives

• Ensure developers can run the app locally on emulator/device within Day 1–2.
• Standardize tooling, SDK versions, and configurations.
• Minimize “it works on my machine” issues.

Step-by-Step Setup Process

Step 1 – Prerequisites

• Install base tools:
  • Git + SSH key setup
  • Node.js (for React Native) or Dart SDK (for Flutter)
  • Java JDK (11 or required version)
  • Android Studio (with SDK + Emulator)
  • Xcode (for iOS) + Command Line Tools
  • CocoaPods (for iOS RN projects) → sudo gem install cocoapods
  • Device drivers (if testing on physical devices)

Step 2 – Repo & Branch Setup

• Clone repo:
• git clone git@github.com:org/mobile-app.git
• cd mobile-app
• Checkout development branch:
• git checkout develop

Step 3 – Dependency Installation

• For React Native:
• npm install
• cd ios && pod install && cd ..
• For Flutter:
• flutter pub get

Step 4 – Environment Variables

• Copy sample env:
• cp .env.example .env
• Fill values:
  • API base URL (staging/dev)
  • Auth keys (Firebase, AWS Cognito, etc.)
  • Third-party SDK tokens (Google Maps, Stripe test keys)
• Store .env in secure vault → never commit to repo.

Step 5 – Run App (Android)

• Start Android Emulator via Android Studio.
• For React Native:
• npm run android
• For Flutter:
• flutter run

Step 6 – Run App (iOS)

• Open .xcworkspace in Xcode (React Native) OR run via Flutter:
• npm run ios
• # OR
• flutter run
• Ensure proper simulator selected (e.g., iPhone 14).

Step 7 – Verify Setup

• Confirm app builds without errors.
• Test login with default dev account.
• Confirm API call works (via staging backend).
• Submit test commit + PR to validate repo access & CI/CD integration.

Best Practices

• Use NVM (for RN) or FVM (Flutter Version Manager) to lock SDK versions.
• Run lint + format before every commit.
• Use emulators for consistency, but also test on at least one real device per sprint.
• Document any new dependencies added for future devs.

Do’s & Don’ts

Do’s

• Keep Android/iOS SDK versions aligned with project config.
• Use sample .env.example → never create random env keys.
• Regularly clean build folders if facing errors (npx react-native-clean-project, flutter clean).

Don’ts

• Don’t install multiple conflicting SDK versions.
• Don’t commit .env, Pods/, or node_modules/.
• Don’t skip pod install on iOS RN projects (causes build failures).

Outcome

• Developers can set up and run mobile projects locally in 1–2 days.
• Standardized builds across devices and OS.
• Directly supports EPIC 1 – Doc 1 (Onboarding SOP) and Doc 2 (Onboarding Kit).

Purpose

To provide a standardized local development setup guide for web projects, ensuring all developers work in a consistent, reproducible environment across frontend and backend stacks.

Scope

• Applies to all web development projects (frontend, backend, full-stack).
• Used by Developers, Tech Leads, and DevOps Engineers.
• Covers environment setup, package installation, configuration, and verification.

Objectives

• Ensure new devs can spin up projects locally within a day.
• Standardize tools, configurations, and dependencies.
• Avoid “works on my machine” issues.

Step-by-Step Setup Process

Step 1 – Prerequisites

• Install the following (versions to be specified in each project’s README):
  • Node.js + NVM (LTS version, e.g., v18.x).
  • Package Manager: npm or yarn (consistent per project).
  • Git (with SSH key configured).
  • Docker Desktop (for DB and services, if project uses containers).
  • Database Client (e.g., PgAdmin, TablePlus, or MySQL Workbench).
  • IDE: VS Code (with extensions from checklist).

Step 2 – Repo & Branch Setup

• Clone project repo:
• git clone git@github.com:org/project-name.git
• cd project-name
• Checkout appropriate branch:
• git checkout develop
• Pull latest updates:
• git pull origin develop

Step 3 – Dependency Installation

• Install dependencies:
• npm install
• # or
• yarn install
• Verify no peer dependency conflicts.
• If project uses monorepo (Nx, Lerna, Turborepo), run workspace install.

Step 4 – Environment Variables

• Copy sample env file:
• cp .env.example .env
• Fill with:
  • API URLs (staging/dev).
  • Database credentials (read-only for dev).
  • Third-party service keys (e.g., Firebase, Stripe test keys).
• Store secrets securely (never commit .env to repo).

Step 5 – Database Setup

• Start database (if containerized):
• docker-compose up -d
• Run migrations:
• npm run migrate
• Seed dev database if required:
• npm run seed

Step 6 – Run Local Build

• Start development server:
• npm run dev
• Verify at http://localhost:3000 (frontend) and http://localhost:4000 (backend).
• Run API health check endpoint: /health.

Step 7 – Verification

• Confirm:
  • Builds without errors.
  • Connects to staging DB or mock DB.
  • Default test user can log in.
• Submit a test commit + PR (to confirm repo access + CI triggers).

Best Practices

• Always use NVM for Node version control.
• Keep dependencies updated monthly.
• Use Dockerized services for consistency across machines.
• Add pre-commit hooks (lint + format) to avoid code style drift.

Do’s & Don’ts

Do’s

• Follow the .env.example strictly — don’t improvise keys.
• Document any new setup step you discover.
• Use aliases in terminal (e.g., npm run db:migrate).

Don’ts

• Don’t hardcode credentials in config files.
• Don’t install global dependencies unless mandated.
• Don’t skip initial migrations (causes inconsistent states).

Outcome

• Every dev can set up a local environment within 1 day.
• Consistent, reproducible builds across all dev machines.
• Directly supports EPIC 1 – Doc 1 (Onboarding SOP) and Doc 2 (Onboarding Kit).

Purpose

To provide a structured process for collecting, producing, and publishing testimonials and case studies.

This ensures social proof is consistently generated and integrated into marketing campaigns for higher trust and conversions.

Scope

• Applies to B2B SaaS and B2C service clients.
• Used by Customer Success, Sales, and Marketing Teams.
• Covers testimonial requests, case study creation, approval, and publishing.

Objectives

• Systematically capture customer success stories.
• Build short-form testimonials (snippets, reviews, ratings) and long-form case studies.
• Repurpose proof content into ads, landing pages, nurture emails, and PR.

Step 1 – Identify Success Candidates

• Trigger points:
  • Closed-Won deal (after onboarding).
  • Positive feedback from surveys (Doc 6).
  • High NPS (>8) customers.
  • “Champion users” who actively advocate.

Step 2 – Testimonial Collection Process

1. Request Format:
   • Email/CRM automation: “Would you be open to sharing a quick testimonial?”
   • Incentives (if B2C): discount on next booking.
2. Capture Options:
   • Text (email/quote).
   • Video (Zoom snippet, mobile recording).
   • Review platforms (G2, Google Reviews).
3. Approval:
   • Send draft version to customer for confirmation.

Example Outputs:

• B2B SaaS: “Our churn dropped 30% within 3 months thanks to [Tool].”
• B2C Service: “I finally feel safe booking cleaners – verified and reliable!”

Step 3 – Case Study Creation Workflow

Case Study Template

Step 4 – Repurposing Proof Content

• Ads: Use testimonial quotes in creatives.
• Landing Pages: Add case studies under CTAs.
• Emails: Insert customer quotes in nurture flows.
• PR/Media: Use long-form case studies for credibility pitching.
• Social Media: Create reels/carousels with customer stories.

Step 5 – Maintenance

• Maintain a Proof Library (folder/CRM repository).
• Tag content by Persona, Funnel Stage, and ICP segment.
• Refresh with new stories every quarter.

Do’s & Don’ts

Do’s

• Always get written approval before publishing.
• Highlight metrics + emotions (proof + human touch).
• Keep tone authentic, not overly polished.

Don’ts

• Don’t invent or exaggerate results.
• Don’t publish without consent.
• Don’t overuse one testimonial everywhere → rotate stories.