PCM Development/Roles and rights management

Palladio Developer Wiki

• Palladio - Home
• Download
• Features
• Screenshots
• Documentation

Overview

We currently use the following technologies to administrate the Palladio development process:

• GitHub organization: source code management
• JIRA: project management and issue tracking

Motivation

• Current situation: Project participants must be recorded and managed redundantly in GitHub organization and JIRA
• Problem: change of team members too dynamic, results in high maintenance effort
• Thus: Team structures (team organization) should not be mapped in GitHub organization and JIRA, but only access management (technical rights view)

Goal

• Unification of roles & rights management for GitHub organization and JIRA
• MDSD Tools GitHub organization should also be managed with downstream rules for Palladio GitHub organization.

General role concept

Overview on the identified cross-organizational roles

Cross-organizational roles

Cross-organizational roles	Member
Administrators	JIRA: Rollen/PCM Strategisch, Rollen/Jira] (https://sdqweb.ipd.kit.edu/wiki-intern/Rollen)
Employees	Doktoranden, Professoren; Lehrstuhl KIT, FZI, Lehrstuhl Stuttgart
studentische wissenschaftliche Mitarbeiter in the context of Palladio	HIWIs
Students & external partners	e.g. Industriepartner

Overview on the role assignment for GitHub organization and JIRA (incl. read/write rights); these are statically guaranteed by the GitHub rights management.

Overview Role assignment GitHub organization and JIRA

General	GitHub-Orga	Jira
Administrators	Owner	site-admins/jira-administrators
Employees	Member (in Repos Write/Maintain/Admin)	jira-developers
studentische wissenschaftliche Mitarbeiter	Member (NO admin in repos)	jira-developers
Students & external partners	outside collaborator (min. in 1 Repo.) (NO admin in repos)	jira-user
Others	outside collaborator (first time contributor)	jira-software-users

Further information on GitHub roles:

• Repository roles: https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role
• Outside Collaborators: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators
• Organization members: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-members
• Organization owners: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners

Best practices: Rules for working with GitHub

Organizational

• Employees can add their own students as admins, but must also remove them
• Employees can create their own repositories in the organization
  • follow naming convention
  • define (normally creator of the repo)
  • topic 'incubation' should be assigned (repo is therefore not part of the update site, the release and the product)
• Employees are responsible for the maintenance of their created repos (i.e. archiving, making decisions about end-of-life, transferring responsibility to the community if necessary) -> Assume responsibilities according to https://sdqweb.ipd.kit.edu/wiki/Code_Repositories#Repository_Owners
• Best practice in dealing with merge strategy
  • Employees in the role of admin can push directly to the master on their created repos
  • for everyone else, branch protection should be enabled on the 'master' branch within the repos; Source code contributions can only be integrated via pull request (PR)
  • for more details see https://sdqweb.ipd.kit.edu/wiki/PCM_Development/Build_Infrastructure/Github_Repository_Organization

Technical

• Combine multiple commits or PRs across different branches that serve a larger purpose/development goal into a single branch and merge this branch in a PR. Rebase is the default. However, for high-frequency, granular, or confusing commit activity, perform a squash merge.
  • Advantages:
    • Improved clarity of commit history on the master/main branches. Numerous small commits/merges can clutter these branches and make changes hard to track.
    • Changes can be tested via automated builds in the PRs. This applies not only to small incremental changes but also to large consolidated changes, ensuring build correctness.
    • Large changes in PRs are easier for other developers to review.

• Changes to core repositories (marked with the `release` tag on GitHub) must be discussed in the Palladio ConCall (or directly with core maintainers for urgent cases) and require at least two reviews from Palladio organization members.
  • Advantages:
    • This ensures the stability of the core for all dependent users.
    • Beyond the core maintainers, only a few individuals have a comprehensive understanding of the broader impact even small core changes might have.
  • Procedure:

1. Create an issue describing the changes and their purpose.
2. Add an agenda item for the next ConCall.
3. [In parallel with step 2] Prepare changes in branches and open Pull Requests.
4. Discuss the changes in the ConCall and implement any resulting requirements.
5. Once work is completed and builds in the PR pass successfully, assign the PR to the individuals discussed in the ConCall.
6. After all reviewer comments and changes are addressed and the PR is approved, merge the PR into the master/main branch.

• Changes to non-functional, generated, or platform-dependent code should not be committed. Examples include:
  • Java version set in bundles. These are only updated for build changes, as they might alter the supported platform.
    • Example: Java 17 is sometimes changed locally to J2SE-1.5 during builds depending on the locally installed Java version.
  • Changes to `.gitignore` files referencing Tycho artifacts resulting from failed builds. Use `mvn clean` to remove these.
    • Example: `*.polyglot.META-INF`
  • Deleting `.gitkeep` files in `src-gen` or `xtext-gen` folders. These are necessary to avoid warnings in Eclipse or empty folder issues in GitHub.
    • Benefit: When adding a new model with `mwe2` workflows for automatic generation during the build, these files and folders must exist; otherwise, Maven might throw errors.
  • Adjusting spacing in older source code.
    • For small changes, this can make the commit unclear.
    • For larger refactorings, spacing adjustments can be included.

• Changes to build-specific repositories that impact Palladio's internal quality assurance or nightly builds must not be made without consultation with core maintainers or discussion in the Palladio ConCall. The rules for core repositories also apply here.
  • Excluded from this rule are minor changes to the `build.yml` configuration files in individual repositories, such as:
    • `runner-label`: Changing the runner from `self-hosted` to `ubuntu-latest`.
    • `skipBranchDeploy`: Setting to `false` if branch artifacts are needed on the update site (usually for large multi-repository changes or project work).
    • `use-display-output`: Setting to `true` if graphical tests exist.
    • `java-version`: Testing with an older or newer Java version. However, for code on the master/main branches, only the currently supported Java version should be used.
    • `build-repository`: Specifying a repository for changes or using a custom aggregated build of multiple repositories.

• Use clear and descriptive commit messages:
  • Negative example: `added build files` for a change in a `.gitignore` file.
  • Better: `added Tycho build files to gitignore`.

• For maintainability, it is essential to adhere to the principles of good software development and design as taught in the programming and SWT2 lectures.

Workflows

JIRA

• Registration: Developers/users must log in to JIRA by registering (the same workplace email address should be used as for git account to enable assignment during development work)
• Joining the group:
  • by default (role: jira-software-users); have only read rights but no write permissions
  • for write permissions: JIRA admins must become active and assign a role to the registered user( default: jira-user, for developers jira-developer)

GitHub

• Registration with GitHub: Create user account on GitHub
• Joining the organization 'Palladio' (as member or outside collaborator)
  • member: GitHub administrators must become active and assign corresponding roles according to table see above.
  • outside collaborator: repository owner must become active and assign corresponding roles to repo access