Skip to content

Rearrange README so that Summary is at the top #838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 9, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 92 additions & 89 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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:
Expand All @@ -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)