Skip to content

Contributing

Jump to bottom
Jordi Massaguer Pla edited this page Sep 17, 2021 · 30 revisions

Code and documentation

To know what piece of software is where, you can check https://www.uyuni-project.org/pages/source-code.html

Changelogs

If you change something relevant for the user, a changelog entry must be added to all affected packages. How to do that depends on where the packages are being developed (details below)

All changelog entries must follow https://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM).

In particular:

  • You shall not modify any existing component (where component is a text enclosed between ----------).
  • Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace.
  • Limit your maximum line length to 67 characters.
  • All entries must start with a dash (-). You can add second-level using asterisks (*). Third-level or deeper bullet points are not defined, but in any case do NOT use asterisks for it.
  • If you add product names, use the right capitalization and format.
  • Use the rigth indentation for each line.
  • If you bump the package version because of changes from upstream, make sure the list of changes is on a second-level list

Very important: the changelogs must be understandable for users, and relevant for them.

Some examples of wrong changelog entries:

- Fixed a crash

What crash?

- Port PR #1165 from upstream

What's that PR about?

- Enable OpenSuSE 15.3 as a supported client

Name is openSUSE Leap

- cobbler20-setup was removed

Why?

- Enable support for the following products:
  + openSUSE Leap 15.3
  + SLE Micro 5.2

Use * instead of + for the second level list.

- Enable support for the following products:
* openSUSE Leap 15.3
* SLE Micro 5.2

Wrong indentation

- Update to grafana 5.1.6
- Refresh branding
- Change authentication method to use LDAP by default

Changes for 5.1.6 should be on a second level list.

Submitting to Git

We work with Pull Requests, so you need to be familiar with them and with the concept of forking.

  1. If this is your first contribution: fork the git repository you want to change, and then clone it to your computer.

    If this is not your first contribution: Go to your local clone and make sure your master branch is synced against upstream.

  2. Create a new branch from master.

  3. Develop the feature or the bugfix on that branch: code, tests and changelogs (last two where applicable).

    You can freely commit and push. Pushes will go to your forked repository at this stage.

    Amend commits or squash them together when it makes sense.

    IMPORTANT: In most cases, specially if you plan to submit to the uyuni-project/uyuni, you need to add a changelog to be used for the RPM/Deb packages.

  4. Create a Pull Request. The base branch will always be master.

    For the uyuni-project/uyuni repository you will need to fill a template explaining the changes. Use the checkboxes and pay attention to the data requested (for example screenshots if it makes sense)

  5. If you are developing a new feature (or changing an existing one) that is covered by the documentation, you need to prepare Pull Request for this.

    Reference the Pull Requests for the documentation at the Pull Request for the code.

  6. A reviewer should self-assign soon and will either merge the Pull Request or request clarifications or changes.

    NOTE: We plan to add automation to assign reviewers automatically.

Changelog rules for packages at Git

uyuni-project/uyuni repository

In general there should always be changelogs for all PRs, with some exceptions:

  • You are fixing a test.
  • You are changing something that doesn't affect a package.

Procedure:

  1. Check what packages your PR is changing. The easiest way is checking the folder rel-eng/packages. Each file there represent a package and contains the current version of the package, and the path for the package. Inside that path you will find a <packagename>.changes file. If your PR affects any of the paths or children of such paths, you need a changelog entry.
  2. For each package, open its .changes file.
  3. If the first line on the changes file is a separator (-------------------------------------------------------------------) make sure there's add an empty line on top of it.
  4. Add your new entry on top. For example - Fix taskomatic to avoid crashes when using salt 3000. Do not add a header with the date, your name and your email.
  5. Make sure you commit the changes to the changelogs.
Other repositories

Check their contributing guides for details.

Submitting to Open Build Service (OBS)

There are some packages that we do not maintain in git repositories, but directly on OBS.

Some examples are the patterns or the product definitions.

To update such packages we use OBS branches.

  1. Branch the package
  2. Checkout the package to your local computer.
  3. Change the package as needed (update sources, update patches, or update the SPEC, as applies)
  4. Use osc vc to add changelog entries. Remember the guidelines above.
  5. Commit your changes to your branched package (`osc ci -m "")
  6. Create a SR (osc sr or do it from the web interface).

Help others

You can help other people on the mailing lists, Gitter or by testing and reporting bugs.

Check the Contact Page for the details

Translations

Check the Translations section.

Clone this wiki locally