Skip to content

Commit

Permalink
Clarify CONTRIBUTING
Browse files Browse the repository at this point in the history
Adding some details that should make the contributing process clearer.
  • Loading branch information
rpspringuel committed Feb 28, 2025
1 parent 983ed15 commit fea45e4
Showing 1 changed file with 15 additions and 4 deletions.
19 changes: 15 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,11 @@ TeX code must use LuaTeX (more than TeX + eTeX + Omega + PDFTeX) primitives as m

Before submitting a change, please run the tests in [gregorio-test](gregorio-project/gregorio-test) against your resulting code.

When your changes are significant, please provide a test demonstrating the change. See [test documentation](https://github.com/gregorio-project/gregorio-test/blob/master/README.md).
When your changes are significant, please provide a test demonstrating the change. See [test documentation](https://github.com/gregorio-project/gregorio-test/blob/master/README.md) for more information on how the test repository is organized and used.

If your change breaks some of the existing tests, then please either fix the existing tests or propose the new results be accepted as more "correct" than the old ones.

If you are submitting a new or modified test, please create a new branch in the test repository (preferably with a name which matches the name of the branch your changes are on in the main repository) where you can make these changes. Then create a pull request in the test repository which explains your changes and make sure to reference the corresponding pull request in the main repository. This way those reveiwing your changes can also see what you expect the new test results to be.
If you are submitting a new or modified test, please create a new branch in the test repository (preferably with a name which matches the name of the branch your changes are on in the main repository) where you can make these changes. Please make separate commits showing both the before and after behavior of the test(s). Then create a pull request in the test repository which explains your changes and make sure to reference the corresponding pull request in the main repository. This way those reveiwing your changes can also see what you expect the new test results to be.

### Documentation

Expand All @@ -86,7 +86,18 @@ You must also document it in the right places:

### Git Workflow

The Gregorio team is following the [classical Github workflow](https://guides.github.com/introduction/flow/). More precisely it follows what is sometimes described as "[Gitflow Worflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)", keeping the same branch naming convention.
The Gregorio team is following the [classical Github workflow](https://guides.github.com/introduction/flow/). More precisely it follows what is sometimes described as "[Gitflow Worflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)", with some minor modifications to account for the release constraints of TeX Live. Our longterm branches are as follows:

1. `master`
This branch contains the current stable release. No commits should be made directly to this branch, only merges from a release or hotfix branch (see below).
2. `ctan`
This branch is a development branch used for changes which are compatible with the executable that has been uploaded to CTAN (and is present in the current year's TeX Live). Pull requests for bugfixes and features which do not affect the executable (and which do not require a major version change) should be made against this branch. Releases from this branch can be made at any time.
3. `develop`
This is the primary development branch for significant changes to the package. All changes to the executable are automatically considered significant, even if they are only a bugfix. Releases from this branch can only be made during the TeX Live pretest (generally during February each year).

We also reserve short-term branch names of the patterns `release-vx.y` and `hotfix-vx.y.z`. Names of this sort are reserved for preparing releases. Only PRs for blocking bugs should be submitted against these branches.

Individual bugfixes and features should be developed on their own branch and then a PR submitted in the main repository against the appropriate branch. New contributors should fork the repository on GitHub under your own username and use branches created there to create PRs against the main repository. If you don't have a GitHub account (they are free) and don't want to create one, you can submit a patch file to the developers' mailing list: [email protected].

### Make a pull request

Expand All @@ -95,5 +106,5 @@ Once you are ready to contribute code:
* fork the repository and checkout your fork
* create a new branch for the pull request you want to make
* commit your changes to this new branch
* make a pull request from this new branch to the relevant branch (usually `develop`)
* make a pull request from this new branch to the relevant branch (see above)
* the Gregorio developers will inspect and comment your pull request, and finally merge it (or not)

0 comments on commit fea45e4

Please sign in to comment.