From e6a6a6537eee072fe413fab8249e497d01350a67 Mon Sep 17 00:00:00 2001 From: James Couball Date: Wed, 9 Jul 2025 12:21:06 -0700 Subject: [PATCH] docs: rearrange README so that Summary is at the top This change moves all the project announcement to a new section at the end of the document. They are discoverable in the table of contents at the top of the document still. --- README.md | 181 +++++++++++++++++++++++++++--------------------------- 1 file changed, 92 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 415e48d6..6d11d0b7 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,6 @@ [![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=main)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) -- [📢 Architectural Redesign 📢](#-architectural-redesign-) -- [📢 We Now Use RuboCop 📢](#-we-now-use-rubocop-) -- [📢 Default Branch Rename 📢](#-default-branch-rename-) -- [📢 We've Switched to Conventional Commits 📢](#-weve-switched-to-conventional-commits-) - [Summary](#summary) - [Install](#install) - [Major Objects](#major-objects) @@ -24,88 +20,11 @@ - [Examples](#examples) - [Ruby version support policy](#ruby-version-support-policy) - [License](#license) - -## 📢 Architectural Redesign 📢 - -The git gem is undergoing a significant architectural redesign for the upcoming -v5.0.0 release. The current architecture has several design challenges that make it -difficult to maintain and evolve. This redesign aims to address these issues by -introducing a clearer, more robust, and more testable structure. - -We have prepared detailed documents outlining the analysis of the current -architecture and the proposed changes. We encourage our community and contributors to -review them: - -1. [Analysis of the Current Architecture](redesign/1_architecture_existing.md): A - breakdown of the existing design and its challenges. -2. [The Proposed Redesign](redesign/2_architecture_redesign.md): An overview of the - new three-layered architecture. -3. [Implementation Plan](redesign/3_architecture_implementation.md): The step-by-step - plan for implementing the redesign. - -Your feedback is welcome! Please feel free to open an issue to discuss the proposed -changes. - -> **DON'T PANIC!** -> -> While this is a major internal refactoring, our goal is to keep the primary public -API on the main repository object as stable as possible. Most users who rely on -documented methods like `g.commit`, `g.add`, and `g.status` should find the -transition to v5.0.0 straightforward. -> -> The breaking changes will primarily affect users who have been relying on the -internal g.lib accessor, which will be removed as part of this cleanup. For more -details, please see the "Impact on Users" section in [the redesign -document](redesign/2_architecture_redesign.md). - -## 📢 We Now Use RuboCop 📢 - -To improve code consistency and maintainability, the `ruby-git` project has now -adopted [RuboCop](https://rubocop.org/) as our static code analyzer and formatter. - -This integration is a key part of our ongoing commitment to making `ruby-git` a -high-quality, stable, and easy-to-contribute-to project. All new contributions will -be expected to adhere to the style guidelines enforced by our RuboCop configuration. - - RuboCop can be run from the project's Rakefile: - -```shell -rake rubocop -``` - -RuboCop is also run as part of the default rake task (by running `rake`) that is run -in our Continuous Integration workflow. - -Going forward, any PRs that have any Robocop offenses will not be merged. In -certain rare cases, it might be acceptable to disable a RuboCop check for the most -limited scope possible. - -If you have a problem fixing a RuboCop offense, don't be afraid to ask a contributor. - -## 📢 Default Branch Rename 📢 - -On June 6th, 2025, the default branch was renamed from 'master' to 'main'. - -Instructions for renaming your local or forked branch to match can be found in the -gist [Default Branch Name -Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d). - -## 📢 We've Switched to Conventional Commits 📢 - -To enhance our development workflow, enable automated changelog generation, and pave -the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional -Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit -messages. - -Going forward, all commits to this repository **MUST** adhere to the Conventional -Commits standard. Commits not adhering to this standard will cause the CI build to -fail. PRs will not be merged if they include non-conventional commits. - -A git pre-commit hook may be installed to validate your conventional commit messages -before pushing them to GitHub by running `bin/setup` in the project root. - -Read more about this change in the [Commit Message Guidelines section of -CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines) +- [📢 Project Announcements 📢](#-project-announcements-) + - [2025-07-09: Architectural Redesign](#2025-07-09-architectural-redesign) + - [2025-07-07: We Now Use RuboCop](#2025-07-07-we-now-use-rubocop) + - [2025-06-06: Default Branch Rename](#2025-06-06-default-branch-rename) + - [2025-05-15: We've Switched to Conventional Commits](#2025-05-15-weve-switched-to-conventional-commits) ## Summary @@ -608,9 +527,9 @@ end This gem will be expected to function correctly on: -* All non-EOL versions of the MRI Ruby on Mac, Linux, and Windows -* The latest version of JRuby on Linux -* The latest version of Truffle Ruby on Linus +- All non-EOL versions of the MRI Ruby on Mac, Linux, and Windows +- The latest version of JRuby on Linux +- The latest version of Truffle Ruby on Linus It is this project's intent to support the latest version of JRuby on Windows once the following JRuby bug is fixed: @@ -621,3 +540,87 @@ jruby/jruby#7515 Licensed under MIT License Copyright (c) 2008 Scott Chacon. See LICENSE for further details. + +## 📢 Project Announcements 📢 + +### 2025-07-09: Architectural Redesign + +The git gem is undergoing a significant architectural redesign for the upcoming +v5.0.0 release. The current architecture has several design challenges that make it +difficult to maintain and evolve. This redesign aims to address these issues by +introducing a clearer, more robust, and more testable structure. + +We have prepared detailed documents outlining the analysis of the current +architecture and the proposed changes. We encourage our community and contributors to +review them: + +1. [Analysis of the Current Architecture](redesign/1_architecture_existing.md): A + breakdown of the existing design and its challenges. +2. [The Proposed Redesign](redesign/2_architecture_redesign.md): An overview of the + new three-layered architecture. +3. [Implementation Plan](redesign/3_architecture_implementation.md): The step-by-step + plan for implementing the redesign. + +Your feedback is welcome! Please feel free to open an issue to discuss the proposed +changes. + +> **DON'T PANIC!** +> +> While this is a major internal refactoring, our goal is to keep the primary public +API on the main repository object as stable as possible. Most users who rely on +documented methods like `g.commit`, `g.add`, and `g.status` should find the +transition to v5.0.0 straightforward. +> +> The breaking changes will primarily affect users who have been relying on the +internal g.lib accessor, which will be removed as part of this cleanup. For more +details, please see the "Impact on Users" section in [the redesign +document](redesign/2_architecture_redesign.md). + +### 2025-07-07: We Now Use RuboCop + +To improve code consistency and maintainability, the `ruby-git` project has now +adopted [RuboCop](https://rubocop.org/) as our static code analyzer and formatter. + +This integration is a key part of our ongoing commitment to making `ruby-git` a +high-quality, stable, and easy-to-contribute-to project. All new contributions will +be expected to adhere to the style guidelines enforced by our RuboCop configuration. + + RuboCop can be run from the project's Rakefile: + +```shell +rake rubocop +``` + +RuboCop is also run as part of the default rake task (by running `rake`) that is run +in our Continuous Integration workflow. + +Going forward, any PRs that have any Robocop offenses will not be merged. In +certain rare cases, it might be acceptable to disable a RuboCop check for the most +limited scope possible. + +If you have a problem fixing a RuboCop offense, don't be afraid to ask a contributor. + +### 2025-06-06: Default Branch Rename + +On June 6th, 2025, the default branch was renamed from 'master' to 'main'. + +Instructions for renaming your local or forked branch to match can be found in the +gist [Default Branch Name +Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d). + +### 2025-05-15: We've Switched to Conventional Commits + +To enhance our development workflow, enable automated changelog generation, and pave +the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional +Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit +messages. + +Going forward, all commits to this repository **MUST** adhere to the Conventional +Commits standard. Commits not adhering to this standard will cause the CI build to +fail. PRs will not be merged if they include non-conventional commits. + +A git pre-commit hook may be installed to validate your conventional commit messages +before pushing them to GitHub by running `bin/setup` in the project root. + +Read more about this change in the [Commit Message Guidelines section of +CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)