From c300bcff0da6334b52fb9e3620fd52c7b3c6978f Mon Sep 17 00:00:00 2001 From: Chinmay-KB Date: Sat, 21 Mar 2026 18:23:55 +0530 Subject: [PATCH] docs: add repo meta foundation --- .github/ISSUE_TEMPLATE/bug_report.yml | 60 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/docs_improvement.yml | 25 ++++ .github/ISSUE_TEMPLATE/feature_request.yml | 33 +++++ .github/ISSUE_TEMPLATE/unicode_edge_case.yml | 52 +++++++ .github/pull_request_template.md | 17 +++ AGENTS.md | 68 +++++++++ CODE_OF_CONDUCT.md | 47 ++++++ CONTRIBUTING.md | 146 ++++++++++++++----- README.md | 7 + SECURITY.md | 37 +++++ SUPPORT.md | 29 ++++ example/pubspec.lock | 2 +- 13 files changed, 491 insertions(+), 40 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/docs_improvement.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/unicode_edge_case.yml create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b4687ec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: Bug report +description: Report a bug, regression, or unexpected behavior in stringr. +title: "[Bug]: " +labels: + - bug +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What went wrong? + placeholder: A short description of the bug. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction + description: Share the smallest example that reproduces the issue. + placeholder: | + import 'package:stringr/stringr.dart'; + + void main() { + print('example'.someMethod()); + } + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect to happen? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead? + validations: + required: true + - type: input + id: version + attributes: + label: stringr version + placeholder: 1.2.1 + validations: + required: true + - type: input + id: dart_version + attributes: + label: Dart version + placeholder: Dart 3.x + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional context + description: Add screenshots, environment notes, or related details if helpful. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..5d2bdd1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security policy + url: https://github.com/Chinmay-KB/stringr/blob/master/SECURITY.md + about: Please review the security policy before reporting a sensitive issue. + - name: Contribution guide + url: https://github.com/Chinmay-KB/stringr/blob/master/CONTRIBUTING.md + about: Read the contribution guide before opening a pull request. diff --git a/.github/ISSUE_TEMPLATE/docs_improvement.yml b/.github/ISSUE_TEMPLATE/docs_improvement.yml new file mode 100644 index 0000000..d784c01 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_improvement.yml @@ -0,0 +1,25 @@ +name: Documentation improvement +description: Report missing, unclear, or incorrect documentation. +title: "[Docs]: " +labels: + - documentation +body: + - type: textarea + id: location + attributes: + label: Location + description: Which file, page, or section needs improvement? + placeholder: README.md, CONTRIBUTING.md, API docs, examples, etc. + validations: + required: true + - type: textarea + id: issue + attributes: + label: What is unclear or missing? + validations: + required: true + - type: textarea + id: suggestion + attributes: + label: Suggested improvement + description: Optional, but helpful if you already know what would make the docs clearer. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..a663ba6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: Feature request +description: Propose a new API, enhancement, or behavior change. +title: "[Feature]: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: Problem or use case + description: What are you trying to do that stringr does not support well today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the API or behavior you would like to see. + validations: + required: true + - type: textarea + id: examples + attributes: + label: Examples + description: Share example inputs and expected outputs. + placeholder: | + Input: ... + Output: ... + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Have you tried existing methods or workarounds? diff --git a/.github/ISSUE_TEMPLATE/unicode_edge_case.yml b/.github/ISSUE_TEMPLATE/unicode_edge_case.yml new file mode 100644 index 0000000..76cfd4a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/unicode_edge_case.yml @@ -0,0 +1,52 @@ +name: Unicode edge case +description: Report behavior involving graphemes, combining marks, emoji, casing, transliteration, or non-Latin scripts. +title: "[Unicode]: " +labels: + - bug + - unicode +body: + - type: textarea + id: input + attributes: + label: Input string + description: Provide the exact input string. Include escaped form too if helpful. + placeholder: "👨‍👩‍👧‍👦 family / café / XMLHttpRequest / полет птицы" + validations: + required: true + - type: input + id: method + attributes: + label: Method or API used + placeholder: slugify(), words(), reverse(), camelCase() + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction + description: Share a small runnable example. + placeholder: | + import 'package:stringr/stringr.dart'; + + void main() { + print('café'.countGrapheme()); + } + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected output + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual output + validations: + required: true + - type: textarea + id: notes + attributes: + label: Notes + description: Mention script, locale expectations, normalization details, or comparisons with other libraries if relevant. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6f81606 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +## Summary + +Describe the change and why it is needed. + +## Changes + +- + +## Testing + +- [ ] `dart format .` +- [ ] `dart analyze` +- [ ] `dart test` + +## Notes + +Add any compatibility notes, Unicode edge cases, follow-ups, or reviewer context here. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fa58c1a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.md + +## Project Overview + +Stringr is a comprehensive string manipulation library for Dart/Flutter inspired by VocaJS. It provides powerful string operations that work with Latin, non-Latin, and grapheme cluster strings using complex regular expressions rather than simple whitespace splitting. + +**Current Status**: Updated to Dart 3.0+ with modern SDK constraints and comprehensive linting rules. + +## Development Commands + +### Testing + +- `dart test` - Run all tests +- `dart run test_coverage` - Run tests with coverage (used in CI) +- `dart test test/specific_test.dart` - Run specific test file + +### Dependencies + +- `dart pub get` - Install dependencies +- `dart pub upgrade` - Upgrade dependencies + +### Analysis + +- `dart analyze` - Static analysis with comprehensive modern Dart linting rules + +## Architecture Overview + +The library follows a **modular extension-based architecture** with functionality organized into domain-specific modules: + +### Core Modules + +- **`lib/src/case/`** - Case transformations (camelCase, kebabCase, snakeCase, titleCase) +- **`lib/src/chop/`** - String truncation operations (truncate, slice, prune, first, last) +- **`lib/src/count/`** - Counting operations (characters, graphemes, occurrences, words) +- **`lib/src/escape/`** - String escaping/unescaping (HTML, RegExp) +- **`lib/src/manipulate/`** - String manipulation (insert, reverse, slugify, translate, splice) +- **`lib/src/split/`** - String splitting operations (words, chars, codePoints, graphemes) + +### Utility Infrastructure + +- **`lib/src/util/object/`** - Generic utility extensions (ExtendedIterable) +- **`lib/src/util/regex/`** - Pre-compiled regex patterns and constants for Unicode handling +- **`lib/src/util/strings/`** - String utility functions, diacritics mapping, and surrogate pair handling + +### Key Patterns + +- Each module implements a Dart extension on `String` class +- Heavy use of pre-compiled regex patterns for Unicode-aware text processing +- Consistent method signatures with optional parameters and sensible defaults +- Support for complex Unicode scenarios including surrogate pairs and grapheme clusters + +## Dependencies + +- **`characters`** ^1.3.0 - Used for grapheme cluster support and Unicode handling (Flutter-compatible version) +- **`test`** ^1.26.3 - Modern testing framework (dev dependency) + +## Important Notes + +- Project uses dependency overrides for `file` and `watcher` packages to ensure Dart 3.0+ compatibility +- The codebase has comprehensive linting rules enforced through `analysis_options.yaml` +- All tests pass on Dart 3.0+ but there are linting warnings that can be addressed incrementally + +## CI/CD + +- GitHub Actions workflow runs on push/PR to master branch +- Uses latest stable Dart container (`dart:stable`) +- Runs tests with coverage and uploads to Codecov +- Coverage reports stored in `coverage/lcov.info` diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..de32153 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,47 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as contributors and maintainers pledge to make participation in the `stringr` community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Taking responsibility, apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best for the community as a whole + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces. Examples of representing the project include using an official project email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers through GitHub issues or discussions when appropriate. For security-sensitive concerns, use the process described in `SECURITY.md`. + +All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. + +For answers to common questions about this code of conduct, see the [FAQ](https://www.contributor-covenant.org/faq). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94b0fb6..8565f77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,58 +1,126 @@ # Contributing to stringr -Thank you for your interest in contributing to stringr! This document provides guidelines for contributing. +Thanks for helping improve `stringr`. The goal of this project is to be a reliable, Unicode-aware string manipulation library for Dart and Flutter, so contributions that improve correctness, clarity, documentation, and edge-case coverage are all valuable. -## Getting Started +## Ways to contribute -1. Fork the repository -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/stringr.git` -3. Install dependencies: `dart pub get` -4. Run tests: `dart test` +- Fix bugs or improve correctness +- Add or improve tests, especially Unicode-heavy cases +- Improve performance or reduce unnecessary allocations +- Clarify API docs, README examples, or package metadata +- Propose new APIs with clear use cases and examples -## Development Workflow +## Development setup -### Making Changes +1. Fork the repository. +2. Clone your fork: + `git clone https://github.com/YOUR_USERNAME/stringr.git` +3. Move into the project directory: + `cd stringr` +4. Install dependencies: + `dart pub get` +5. Run the test suite: + `dart test` +6. Run static analysis: + `dart analyze` -1. Create a feature branch: `git checkout -b feature/your-feature` -2. Make your changes -3. Run tests: `dart test` -4. Run analysis: `dart analyze` -5. Commit your changes with a descriptive message +## Workflow -### Code Style +1. Create a branch for your change: + `git checkout -b feature/short-description` +2. Make your change in small, reviewable commits. +3. Add or update tests when behavior changes. +4. Run the checks before opening a PR: + - `dart format .` + - `dart analyze` + - `dart test` +5. Open a pull request with a clear explanation of the problem, solution, and any tradeoffs. -- Follow the [Dart style guide](https://dart.dev/guides/language/effective-dart/style) -- Run `dart format .` before committing -- Ensure `dart analyze` passes with no issues +## What we look for -### Testing +### Correctness first -- Add tests for new features -- Ensure all existing tests pass -- Test with both Latin and non-Latin strings when applicable +String handling gets tricky quickly. Please prefer behavior that is: -### Commit Messages +- Unicode-aware +- explicit about limitations +- backed by tests +- consistent across similar APIs -Use clear, descriptive commit messages: -- `feat: add new method for X` -- `fix: handle edge case in Y` -- `docs: update README examples` -- `refactor: improve performance of Z` +If a change affects word boundaries, graphemes, casing, diacritics, transliteration, or slug generation, include examples covering more than plain ASCII where practical. -## Pull Request Process +### Tests -1. Ensure all tests pass -2. Update documentation if needed -3. Update CHANGELOG.md with your changes -4. Submit a pull request with a clear description +Please add tests for: -## Reporting Issues +- the main happy path +- at least one edge case +- Unicode or non-Latin inputs when relevant +- regressions for any reported bug -When reporting issues, please include: -- Dart/Flutter version -- Minimal code to reproduce the issue -- Expected vs actual behavior +Good examples include: -## Questions? +- accented Latin text +- Cyrillic, Greek, or other non-Latin scripts +- emoji and grapheme clusters +- mixed separators and casing inputs such as `XMLHttpRequest` -Feel free to open an issue for questions or discussions. +### API changes + +If you are proposing a new method or changing behavior, include: + +- the use case +- example input and output +- how it compares to existing methods +- any compatibility or migration concerns + +For breaking changes, please open an issue or discussion first unless the fix is clearly necessary. + +## Documentation expectations + +Please update documentation when needed: + +- README examples for user-facing features +- inline docs for public API changes +- CHANGELOG entries for notable changes + +## Pull request checklist + +Before submitting a PR, make sure that: + +- code is formatted with `dart format .` +- `dart analyze` passes +- `dart test` passes +- new behavior is covered by tests +- docs are updated when needed +- the PR description explains the change clearly + +## Commit message suggestions + +Conventional-style messages are welcome, for example: + +- `feat: add grapheme-safe trimming helper` +- `fix: handle combining marks in slugify` +- `docs: expand unicode examples in readme` +- `test: add regression coverage for emoji splitting` + +## Reporting issues + +Please use the GitHub issue templates when possible. The most helpful reports include: + +- Dart and Flutter versions +- package version +- platform or runtime details if relevant +- a minimal reproducible example +- expected behavior +- actual behavior + +If the issue involves a Unicode edge case, include the exact input string and output you expected. + +## Security + +For security-sensitive reports, please follow the guidance in `SECURITY.md` instead of opening a public issue. + +## Questions and support + +For usage questions, ideas, or general help, see `SUPPORT.md`. diff --git a/README.md b/README.md index f6c5323..ef0c111 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,13 @@ Most string libraries fail with complex Unicode. stringr handles: Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. +## Project Health + +- [Contributing Guide](CONTRIBUTING.md) +- [Code of Conduct](CODE_OF_CONDUCT.md) +- [Security Policy](SECURITY.md) +- [Support Guide](SUPPORT.md) + ## License MIT License - see [LICENSE](LICENSE) for details. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..781e0f5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,37 @@ +# Security Policy + +## Supported versions + +Security fixes are expected to target the latest released version of `stringr`. + +| Version | Supported | +| ------- | --------- | +| Latest release | Yes | +| Older releases | No | + +## Reporting a vulnerability + +Please do not open a public GitHub issue for suspected security vulnerabilities. + +Instead: + +1. Use GitHub's private vulnerability reporting or security advisory flow for this repository if it is enabled. +2. If private reporting is not available, open a discussion or issue only after removing any sensitive exploit details and clearly note that you are looking for a secure reporting path. + +When reporting a vulnerability, please include: + +- affected `stringr` version +- a short description of the issue +- impact and potential abuse scenario +- reproduction steps or proof of concept, if safe to share privately +- any suggested mitigation, if known + +You can expect: + +- acknowledgement after the report is reviewed +- a best-effort attempt to validate the issue +- coordination on disclosure timing when a fix is needed + +## Scope notes + +Most issues in this library are likely to be correctness or reliability bugs rather than security vulnerabilities. If you are unsure, it is still okay to start with a private report. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..2386bb4 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,29 @@ +# Support + +## Getting help + +If you need help using `stringr`, want to sanity-check an API idea, or are unsure whether something is a bug, GitHub issues are a good place to start. + +When opening a question, it helps to include: + +- what you are trying to do +- the input and expected output +- the code you tried +- package and Dart versions + +## Where to report what + +- Bug or regression: open an issue +- New feature or API idea: open an issue +- Documentation gap: open an issue +- Security concern: follow `SECURITY.md` + +## Before opening an issue + +Please check: + +- `README.md` for current usage examples +- existing issues for duplicates +- whether the behavior involves Unicode, graphemes, or locale-specific expectations that should be called out explicitly + +Clear examples make it much easier to help quickly. diff --git a/example/pubspec.lock b/example/pubspec.lock index 6399f1a..d6bbb38 100644 --- a/example/pubspec.lock +++ b/example/pubspec.lock @@ -15,6 +15,6 @@ packages: path: ".." relative: true source: path - version: "1.0.0" + version: "1.2.1" sdks: dart: ">=3.4.0 <4.0.0"