Create documentation.md

Author: AhmedESamy

documentation.md

@@ -0,0 +1,84 @@
+## 1. Project Plan for Testing, Implementation, and Validation
+
+### 1.1 Team Roles and Responsibilities
+Our team consists of **Ahmed, Herdi, Maxim, Annika, and Kim**, with roles distributed as follows:
+
+| **Team Member**  | **Role**  | **Responsibilities**  |
+|----------------|---------|-----------------|
+| **Ahmed**  | Issue Resolution & Implementation  | Implementing fixes for new date formats in `Period` class and modifying `parse_time_string` to integrate logic for these formats. |
+| **Herdi**  | Repository Preparation, Test Execution & Additional Fixes  | Setting up the environment, running the full test suite, integrating fixes, and handling additional bug fixes related to `Period` class behavior. |
+| **Maxim, Annika, Kim**  | Testing Team  | Writing, documenting, and structuring test cases in `test_period.py`. Running and validating test cases before and after implementation. Ensuring coverage analysis is performed. |
+
+---
+
+### 1.2 Current Project Plan
+This project plan outlines how we implemented, tested, and validated the new date formats and additional fixes before merging into pandas.
+
+#### 1.2.1 Issue Overview
+We have implemented four new date formats in the `Period` class:
+
+1. **ISO 8601 Ordinal Dates** (e.g., `"1981-095"` → Interpreted as April 5, 1981).
+2. **Multi-Year Spans** (e.g., `"2019-2021"` → Represents the range of years 2019 to 2021).
+3. **Week Start-End Ranges** (e.g., `"20170123-20170129"` → Interpreted as a full week).
+4. **Quarter-Based Multi-Year Periods** (e.g., `"2023Q1-2024Q3"` → Generates a quarterly range).
+5. **`DateParseError` on weeks from the 24th century onwards**
+6. **`DateParseError` on weeks in the 60s, 70s, 80s, or 90s** of any century.
+7. **Correcting `freq` misinterpretations**, ensuring that hours are no longer mistaken for minutes in certain string formats.
+
+---
+
+#### 1.2.2 Implementation, Testing, and Validation
+The **implementation, testing, and validation** of the new formats and fixes were conducted **in parallel** by the team. All team members contributed to different aspects of development, and the documentation was **iteratively revised and refined** after testing.
+
+##### **Test Preparation (Before Implementation)**
+- The **testing team (Maxim, Annika, and Kim)** worked on:
+  - Writing **test cases** covering the issue requirements/features.
+  - Documenting test cases, describing **what is tested and how they connect** to the feature.
+  - Adding test descriptions as **issue documentation** and **method docstrings** in `test_period.py`.
+  - Executing **test cases to confirm failure before implementation**, validating that the issue exists.
+
+##### **Feature Implementation**
+- **Ahmed** worked on:
+  - Modifying `Period` and `parse_time_string` to **support the new formats**.
+  - Pushing the fixes to a **feature branch** for testing.
+- **Herdi** worked on:
+  - **Integrating the fixes** into the repository.
+  - Ensuring **smooth compatibility** with existing pandas functionality.
+  - **Implementing fixes for additional issues**, including `DateParseErrors` and frequency misinterpretations.
+
+##### **Test Execution (After Implementation)**
+- The **testing team**:
+  - Executed the **full pandas test suite** to verify that new changes do not break existing functionality.
+  - Ran the **new test cases** to ensure they **passed after implementation**.
+
+##### **Coverage and Final Validation**
+- The **testing team** analyzed:
+  - **Test coverage**, ensuring that **key execution paths** were tested.
+  - Re-ran the **full test suite** with `pytest --cov` to verify coverage levels.
+
+---
+
+### 1.2.3. Documentation & Refinement
+Throughout the project, **all team members contributed** to the documentation, ensuring that it accurately described the issue, testing strategy, and implementation details. After completing the implementation and testing, the documentation was **revised and refined** to reflect the final methodology and test results.
+
+#### **Key Documentation Deliverables:**
+- **Issue documentation** describing **requirements, test cases, and feature mapping**.  
+- **Test case descriptions** added to **test_period.py**.  
+- Final **test results and coverage analysis documentation**.  
+- **Structured patch submitted** to pandas for review.
+
+---
+### 1.3 **Future Project Plan: Enhancing `Period` Class**
+
+#### **Planned Features for Next Iteration**
+- **Business Years Not Starting in January**
+  - Support fiscal years with **custom start months** (e.g., `"2023FY-Apr"`).
+  - Modify `Period` parsing to recognize and handle non-January year starts.
+
+- **Quarters Starting in Custom Months**
+  - Extend quarter parsing to support **non-standard starts** (e.g., `"2024Q1-Feb"`).
+  - Ensure consistency with fiscal calendars and existing pandas behavior.
+
+- **Business Days Support**
+  - Introduce **business day-based periods** (e.g., `"2023-05-BD"`).
+  - Align with pandas’ existing **BusinessDay (`BD`) frequency**.