docs: update CONTRIBUTING (#368)

Includes CHANGELOG clean-up
anti-work · Feb 26, 2025 · b420e26 · b420e26
1 parent fea1339
commit b420e26
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 62 deletions.
diff --git a/packages/shortest/CHANGELOG.md b/packages/shortest/CHANGELOG.md
@@ -1,54 +1,8 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.4.1] - 2025-01-07
-
-### Added
-- Update readme with CLI example by @Harry Roper
-- Update README with non-engineer introduction and example tests by @devin-ai-integration[bot]
-- Add token usage details in summary by @khalatevarun
-- Add baseURL configuration to BrowserManager context by @PedroAVJ
-- Update test command example with directory path by @devin-ai-integration[bot]
-- Move AI processing logic to more appropriate location by @PedroAVJ
-
-### Fixed
-- Improve AI handling of newly opened tabs by @rmarescu
-
-## [0.4.0] - 2025-01-02
-
-### Added
-- Chained testing by @crabest
-- 'before' function support by @slavingia
-- Bash tool by @gladyshcodes
-
-### Changed
-- Adjusted the prompt to expect successful test execution by @crabest
-- Updated Copyright year from 2024 to 2025 by @crabest
-- Refactored config to detect test.ts files instead of files under test directory by @khalatevarun
-- Improved index.d.ts generation by @amk-dev
-- Updated shortest.config.ts by @slavingia
-- Updated npm readme by @m2rads
-
-### Removed
-- Removed yarn support by @m2rads
-
-**Full Changelog**: https://github.com/anti-work/shortest/compare/v0.3.0...v0.4.0
-
-## [0.3.0] - 2024-12-30
-
-### Changes
-- Added Caching
-
-## [0.2.1] - 2024-12-27
-
-## Added
-- Mailosaur integration with error handling for email validation
-- Browser-based email preview functionality
-- Test execution delay utility (sleep_milliseconds)
+> [!NOTE]
+> Releases for version v0.2.1 and newer are maintained on the [GitHub Releases page](https://github.com/anti-work/shortest/releases).
+> Older versions are kept here for historical purposes.
 
 ## [0.1.1] - 2024-12-24
 
@@ -142,10 +96,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Browser automation using Playwright
 - CLI tool for running tests
 - Support for ESM and CommonJS
-
-### PeeDependencies
-- Playwright ^1.42.1
-- Anthropic AI SDK 0.32.0
-- esbuild ^0.20.1
-- expect ^29.7.0
-- dotenv ^16.4.5
diff --git a/packages/shortest/CONTRIBUTING.md b/packages/shortest/CONTRIBUTING.md
@@ -23,6 +23,28 @@ cp .env.example .env.local
 # Add your ANTHROPIC_API_KEY to .env.local
 ```
 
+## Feature implementation process
+
+We prioritize issues from the current milestone. Check the [roadmap](https://github.com/orgs/anti-work/projects/5/views/3?query=sort%3Aupdated-desc+is%3Aopen) to see which issues we're focusing on right now.
+
+### Issue states
+
+- **Scoping needed**: The issue requires an implementation plan before development can start. If you want to work on this issue, first create an implementation plan outlining the approach.
+- **Building needed**: The issue has been scoped and is ready for development. You can start implementing it immediately. If you have any clarifying questions, post a comment on the issue.
+
+### Implementation plan
+
+To have an issue moved from _Scoping needed_ to _Building needed_, create an implementation plan that outlines:
+  - technical approach
+  - key components and interfaces
+  - potential challenges
+  - testing strategy
+
+[Create a discussion](https://github.com/anti-work/shortest/discussions/new?category=general) to get feedback on the implementation plan from maintainers before beginning development.
+
+> [!IMPORTANT]
+> We recommend waiting until an issue has moved to _Building needed_ before submitting a PR. PRs for issues in the _Scoping needed_ state might need significant rework or may be put on hold until proper scoping is complete.
+
 ## Development
 
 1. Create your feature branch
@@ -56,20 +78,19 @@ npx shortest -h
 
 ## Pull requests
 
-1. Update documentation if you're changing behavior
+1. Update documentation as needed
 2. Add or update tests for your changes
-3. Update CHANGELOG.md with your changes
-4. Make sure all tests pass
-5. Request a review from maintainers
-6. After reviews begin, avoid force-pushing to your branch
+3. Make sure all tests pass
+4. Request a review from maintainers
+5. After reviews begin, avoid force-pushing to your branch
    - Force-pushing rewrites history and makes review threads hard to follow
    - Don't worry about messy commits - we squash everything when merging to `main`
 
 ## Style guide
 
-- Write in TypeScript
 - Follow the existing code patterns
 - Use clear, descriptive variable names
+- Don't add inline comments unless necessary (code should document itself)
 
 ## Writing commit messages