From b30e63086b55f9f40e58dcad917da878e61daf60 Mon Sep 17 00:00:00 2001 From: Nikita Vasilev Date: Mon, 22 Dec 2025 14:36:01 +0400 Subject: [PATCH] docs: update `README.md` --- CODE_OF_CONDUCT.md | 151 +++++++++---- CONTRIBUTING.md | 534 +++++++++++++++++++++++++++++++++++++++++---- README.md | 262 ++++++++++++++++++---- 3 files changed, 818 insertions(+), 129 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 56c1661..fa7ff7a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,73 +2,132 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. +We as members, contributors, and leaders pledge to make participation in our +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, caste, color, 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 creating a positive environment -include: +Examples of behavior that contributes to a positive environment for our +community include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* 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 electronic - address, without explicit permission +* 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 -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that 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, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +Community leaders 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 both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail 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 by contacting one of the project maintainers https://github.com/orgs/space-code/people. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +reported to the community leaders responsible for enforcement at +nv3212@gmail.com. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03b85d1..75b3858 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,515 @@ -# Contributing Guidelines +# Contributing to FlexUI -This document contains information and guidelines about contributing to this project. -Please read it before you start participating. +First off, thank you for considering contributing to FlexUI! It's people like you that make FlexUI such a great tool. -**Topics** +## Table of Contents -* [Reporting Issues](#reporting-issues) -* [Submitting Pull Requests](#submitting-pull-requests) -* [Developers Certificate of Origin](#developers-certificate-of-origin) -* [Code of Conduct](#code-of-conduct) +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) + - [Development Setup](#development-setup) + - [Project Structure](#project-structure) +- [How Can I Contribute?](#how-can-i-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Features](#suggesting-features) + - [Improving Documentation](#improving-documentation) + - [Submitting Code](#submitting-code) +- [Development Workflow](#development-workflow) + - [Branching Strategy](#branching-strategy) + - [Commit Guidelines](#commit-guidelines) + - [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) + - [Swift Style Guide](#swift-style-guide) + - [Code Quality](#code-quality) + - [Testing Requirements](#testing-requirements) +- [Community](#community) -## Reporting Issues +## Code of Conduct -A great way to contribute to the project is to send a detailed issue when you encounter a problem. We always appreciate a well-written, thorough bug report. +This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to nv3212@gmail.com. -Check that the project issues database doesn't already include that problem or suggestion before submitting an issue. If you find a match, feel free to vote for the issue by adding a reaction. Doing this helps prioritize the most common problems and requests. +See [CODE_OF_CONDUCT.md](https://github.com/space-code/flex-ui/blob/main/CODE_OF_CONDUCT.md) for details. -When reporting issues, please fill out our issue template. The information the template asks for will help us review and fix your issue faster. +## Getting Started -## Submitting Pull Requests +### Development Setup -You can contribute by fixing bugs or adding new features. For larger code changes, we recommend first discussing your ideas on our [GitHub Discussions](https://github.com/space-code/flex-ui/discussions). When submitting a pull request, please add relevant tests and ensure your changes don't break any existing tests. +1. **Fork the repository** + ```bash + # Click the "Fork" button on GitHub + ``` -## Developer's Certificate of Origin 1.1 +2. **Clone your fork** + ```bash + git clone https://github.com/YOUR_USERNAME/flex-ui.git + cd flex-ui + ``` -By making a contribution to this project, I certify that: +3. **Set up the development environment** + ```bash + # Bootstrap the project + make bootstrap + ``` -- (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or +4. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` -- (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or +5. **Open the project in Xcode** + ```bash + open Package.swift + ``` -- (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. +## How Can I Contribute? -- (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. +### Reporting Bugs -## Code of Conduct +Before creating a bug report, please check the [existing issues](https://github.com/space-code/flex-ui/issues) to avoid duplicates. + +When creating a bug report, include: + +- **Clear title** - Describe the issue concisely +- **Reproduction steps** - Detailed steps to reproduce the bug +- **Expected behavior** - What you expected to happen +- **Actual behavior** - What actually happened +- **Environment** - iOS version, Xcode version, Swift version +- **Code samples** - Minimal reproducible example +- **Error messages** - Complete error output if applicable + +**Example:** +```markdown +**Title:** Chainable configuration breaks with custom UIView subclass + +**Steps to reproduce:** +1. Create custom UIView subclass +2. Add .flex configuration chain +3. Attempt to set backgroundColor + +**Expected:** Background color should be set correctly +**Actual:** Compiler error about missing return type + +**Environment:** +- iOS 16.0 +- Xcode 16.0 +- Swift 6.0 + +**Code:** +\`\`\`swift +class CustomView: UIView { } + +let view = CustomView() + .flex + .backgroundColor(.red) // Error here +\`\`\` +``` + +### Suggesting Features + +We love feature suggestions! When proposing a new feature, include: + +- **Problem statement** - What problem does this solve? +- **Proposed solution** - How should it work? +- **Alternatives** - What alternatives did you consider? +- **Use cases** - Real-world scenarios +- **API design** - Example code showing usage +- **Breaking changes** - Will this break existing code? + +**Example:** +```markdown +**Feature:** Add animation helper methods to FlexUI + +**Problem:** Configuring view animations requires breaking the chain and using UIView.animate separately. + +**Solution:** Add chainable animation methods to FlexUI protocol. + +**API:** +\`\`\`swift +let view = UIView() + .flex + .backgroundColor(.blue) + .animate(duration: 0.3) { view in + view.flex + .alpha(0.5) + .transform(CGAffineTransform(scaleX: 1.2, y: 1.2)) + } +\`\`\` + +**Use case:** Creating animated UI without breaking the fluent configuration chain. +``` + +### Improving Documentation + +Documentation improvements are always welcome: + +- **Code comments** - Add/improve inline documentation +- **DocC documentation** - Enhance documentation articles +- **README** - Fix typos, add examples +- **Guides** - Write tutorials or how-to guides +- **API documentation** - Document public APIs -The Code of Conduct governs how we behave in public or in private -whenever the project will be judged by our actions. -We expect it to be honored by everyone who contributes to this project. +### Submitting Code -See [CODE_OF_CONDUCT.md](https://github.com/space-code/flex-ui/blob/master/CODE_OF_CONDUCT.md) for details. +1. **Check existing work** - Look for related issues or PRs +2. **Discuss major changes** - Open an issue for large features +3. **Follow coding standards** - See [Coding Standards](#coding-standards) +4. **Write tests** - All code changes require tests +5. **Update documentation** - Keep docs in sync with code +6. **Create a pull request** - Use clear description + +## Development Workflow + +### Branching Strategy + +We use a simplified branching model: + +- **`main`** - Main development branch (all PRs target this) +- **`feature/*`** - New features +- **`fix/*`** - Bug fixes +- **`docs/*`** - Documentation updates +- **`refactor/*`** - Code refactoring +- **`test/*`** - Test improvements + +**Branch naming examples:** +```bash +feature/animation-helpers +fix/chaining-with-custom-views +docs/update-extension-guide +refactor/simplify-flex-protocol +test/add-uitableview-tests +``` + +### Commit Guidelines + +We use [Conventional Commits](https://www.conventionalcommits.org/) for clear, structured commit history. + +**Format:** +``` +(): + + + +