Skip to content
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

Draft new contribution guide #245

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
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
57 changes: 31 additions & 26 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,41 +4,44 @@ title: Contributing Guide
sidebar_label: Contributing Guide
---

## Thank you for participating
## Thank you for participating

The following is a set of rules for contributing to **Rucio** and its
packages. Use your best judgment, and feel free to propose changes to this
document.

If you have questions, you can reach the core development team on our
[__Mattermost__](mattermost.md) channel, or send an email to our
development mailing list [[email protected]__](mailto:[email protected]).
If you have questions, you can reach the development team on our
[__Mattermost__](mattermost.md) channel.
Comment on lines +13 to +14
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would point them to the contact us page instead: https://rucio.cern.ch/documentation/contact_us


## What should I know before I get started

A contribution can be either be a **patch** or **feature**:
Generally all [__pull requests__](https://github.com/rucio/rucio/pulls) are to
be created against the Rucio **master** branch. The master branch includes the
developments towards the **next** major release. Usually we publish three major
releases per year, thus it might take several months until a development becomes
available in a published release (See [__Release policy__](started/release_policy.md)).

* **Patches** include bugfixes and minor changes to the code and are included in
patch releases usually made on a bi-weekly schedule.
* **Features** include major developments or potentially disruptive changes and
are included in feature releases made multiple times a year.
In addition, a contribution **CAN** be included in the ongoing **current** release
line. As a guiding principle:

The [__repository__](https://github.com/rucio/rucio/) consists of different
branches:
* Larger feature developments, backwards-compatibility breaking changes, changes
to the database schema, significant changes to the REST interface, and similar
**MUST** be targeted towards the **next** release line.
* Bugfixes, smaller backwards-compatbile changes to the REST interface, smaller
feature developments, and similar **CAN** be targeted towards the **current**
release line.

* the **master** branch includes the development for the next major version.
* the **release-…** branches include the patch/minor development of the
releases.
To implement this policy the [__repository__](https://github.com/rucio/rucio/)
consists of different branches:

Release branches only exist for the currently maintained release
versions. Hotfix branches are created on demand. Please communicate to the Rucio
maintainers, if you wish to hotfix a previous release.
* the **master** branch includes the developments towards the next major release.
* the **release-…** branches include the patch/minor developments of the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this sentence is a bit confusing, maybe split?

releases (Such as current and LTS releases). Release branches only exist for
the currently maintained releases (See the [__release policy__](started/releasepolicy.md))

Generally all [__pull requests__](https://github.com/rucio/rucio/pulls) are to
be created against the Rucio **master** branch. Features will end up in the
upstream **master** only and patches are cherry-picked to the maintained
releases if applicable. Release-specific changes are excluded from that rule and
might be needed if e.g. cherry-picking to the last release was not successful.
Pull requests named/targeted for the **next** major release will end up in the
upstream **master** only. Pull requests named/targeted for the **current** release
will be cherry-picked by the maintainer to the applicable release branch.

The following figure might help you with an overview:

Expand Down Expand Up @@ -105,16 +108,18 @@ number**.
Create a local branch that corresponds to the issue. To easily
identify the purpose of branches different keywords must be used:

* Patch branches must be named **patch-[issue number]-[short description]**
* Feature branches must be named **feature-[issue number]-[short description]**
* Contributions targeted to the **current** release must be named
**current-[issue number]-[short description]**
* Contributions targeted to the **next** major release must be named
**next-[issue number]-[short description]**

If you create these branches by hand please check the spelling because otherwise
the test automation might misidentify your branch. There are utility scripts to
fetch master and create these branches for you:

```bash
./tools/create-patch-branch <unique issue number> '<short_change_message>'
./tools/create-feature-branch <unique issue number> '<short_change_message>'
./tools/create-current-branch <unique issue number> '<short_change_message>'
./tools/create-next-branch <unique issue number> '<short_change_message>'
Comment on lines -116 to +122
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these scripts are currently still named create-patch-branch and create-feature-branch

```

### 4. Commit your changes
Expand Down
Loading