- Summary
- How to contribute
- How to report an issue or request a feature
- How to submit a code or documentation change
- Design philosophy
- Coding standards
- Building a specific version of the Git command-line
- Licensing
Thank you for your interest in contributing to the ruby-git
project.
This document provides guidelines for contributing to the ruby-git
project. While
these guidelines may not cover every situation, we encourage you to use your best
judgment when contributing.
If you have suggestions for improving these guidelines, please propose changes via a pull request.
You can contribute in the following ways:
ruby-git
utilizes GitHub
Issues
for issue tracking and feature requests.
To report an issue or request a feature, please create a ruby-git
GitHub
issue. Fill in the template as
thoroughly as possible to describe the issue or feature request.
There is a three-step process for submitting code or documentation changes:
- Commit your changes to a fork of
ruby-git
using Conventional Commits - Create a pull request
- Get your pull request reviewed
Make your changes in a fork of the ruby-git
repository.
If you are not familiar with GitHub Pull Requests, please refer to this article.
Follow the instructions in the pull request template.
Code review takes place in a GitHub pull request using the GitHub pull request review feature.
Once your pull request is ready for review, request a review from at least one maintainer and any other contributors you deem necessary.
During the review process, you may need to make additional commits, which should be
squashed. Additionally, you may need to rebase your branch to the latest master
branch if other changes have been merged.
At least one approval from a project maintainer is required before your pull request can be merged. The maintainer is responsible for ensuring that the pull request meets the project's coding standards.
Note: As of v2.x of the git
gem, this design philosophy is aspirational. Future
versions may include interface changes to fully align with these principles.
The git
gem is designed as a lightweight wrapper around the git
command-line
tool, providing Ruby developers with a simple and intuitive interface for
programmatically interacting with Git.
This gem adheres to the "principle of least surprise," ensuring that it does not
introduce unnecessary abstraction layers or modify Git's core functionality. Instead,
the gem maintains a close alignment with the existing git
command-line interface,
avoiding extensions or alterations that could lead to unexpected behaviors.
By following this philosophy, the git
gem allows users to leverage their existing
knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
and paradigms.
Git commands are implemented within the Git::Base
class, with each method directly
corresponding to a git
command. When a Git::Base
object is instantiated via
Git.open
, Git.clone
, or Git.init
, the user can invoke these methods to interact
with the underlying Git repository.
For example, the git add
command is implemented as Git::Base#add
, and the git ls-files
command is implemented as Git::Base#ls_files
.
When a single Git command serves multiple distinct purposes, method names within the
Git::Base
class should use the git
command name as a prefix, followed by a
descriptive suffix to indicate the specific function.
For instance, #ls_files_untracked
and #ls_files_staged
could be used to execute
the git ls-files
command and return untracked and staged files, respectively.
To enhance usability, aliases may be introduced to provide more user-friendly method names where appropriate.
Parameters within the git
gem methods are named after their corresponding long
command-line options, ensuring familiarity and ease of use for developers already
accustomed to Git. Note that not all Git command options are supported.
The git
gem translates the output of many Git commands into Ruby objects, making it
easier to work with programmatically.
These Ruby objects often include methods that allow for further Git operations where useful, providing additional functionality while staying true to the underlying Git behavior.
To ensure high-quality contributions, all pull requests must meet the following requirements:
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 for all commit
messages.
This structured approach to commit messages allows us to:
- Automate versioning and releases: Tools can now automatically determine the semantic version bump (patch, minor, major) based on the types of commits merged.
- Generate accurate changelogs: We can automatically create and update a
CHANGELOG.md
file, providing a clear history of changes for users and contributors. - Improve commit history readability: A standardized format makes it easier for everyone to understand the nature of changes at a glance.
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.
The simplist conventional commit is in the form type: description
where type
indicates the type of change and description
is your usual commit message (with
some limitations).
- Types include:
feat
,fix
,docs
,test
,refactor
, andchore
. See the full list of types supported in .commitlintrc.yml. - The description must (1) not start with an upper case letter, (2) be no more than 100 characters, and (3) not end with punctuation.
Examples of valid commits:
feat: add the --merges option to Git::Lib.log
fix: exception thrown by Git::Lib.log when repo has no commits
docs: add conventional commit announcement to README.md
Commits that include breaking changes must include an exclaimation mark before the colon:
feat!: removed Git::Base.commit_force
The commit messages will drive how the version is incremented for each release:
- a release containing a breaking change will do a major version increment
- a release containing a new feature will do a minor increment
- a release containing neither a breaking change nor a new feature will do a patch version increment
The full conventional commit format is:
<type>[optional scope][!]: <description>
[optional body]
[optional footer(s)]
optional body
may include multiple lines of descriptive text limited to 100 chars eachoptional footers
only usesBREAKING CHANGE: <description>
where description should describe the nature of the backward incompatibility.
Use of the BREAKING CHANGE:
footer flags a backward incompatible change even if it
is not flagged with an exclaimation mark after the type
. Other footers are allowed
by not acted upon.
See the Conventional Commits specification for more details.
- All changes must be accompanied by new or modified unit tests.
- The entire test suite must pass when
bundle exec rake default
is run from the project's local working copy.
While working on specific features, you can run individual test files or a group of
tests using bin/test
:
# run a single file (from tests/units):
$ bin/test test_object
# run multiple files:
$ bin/test test_object test_archive
# run all unit tests:
$ bin/test
# run unit tests with a different version of the git command line:
$ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
All tests must pass in the project's GitHub Continuous Integration build before the pull request will be merged.
The Continuous Integration
workflow
runs both bundle exec rake default
and bundle exec rake test:gem
from the
project's Rakefile.
New and updated public methods must include YARD documentation.
New and updated public-facing features should be documented in the project's README.md.
To test with a specific version of the Git command-line, you may need to build that version from source code. The following instructions are adapted from Atlassian’s How to install Git page for building Git on macOS.
Prerequisites only need to be installed if they are not already present.
From your terminal, install Xcode’s Command Line Tools:
xcode-select --install
Install Homebrew by following the instructions on the Homebrew page.
Using Homebrew, install OpenSSL:
brew install openssl
Download and extract the source tarball for the desired Git version from this source code mirror.
From your terminal, change to the root directory of the extracted source code and run the build with following command:
NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
The build script will place the newly compiled Git executables in the bin-wrappers
directory (e.g., bin-wrappers/git
).
To configure programs that use the Git gem to utilize the newly built version, do the following:
require 'git'
# Set the binary path
Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
# Validate the version (if desired)
assert_equal([2, 30, 2], Git.binary_version)
Tests can be run using the newly built Git version as follows:
GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
Note: GIT_PATH
refers to the directory containing the git
executable.
ruby-git
uses the MIT license as
declared in the LICENSE file.
Licensing is critical to open-source projects as it ensures the software remains available under the terms desired by the author.