Skip to content

developer-guide: add contribution workflow - #1151

Merged
osfrickler merged 1 commit into
mainfrom
developer-guide-contribution-workflow
Nov 19, 2026
Merged

osfrickler merged 1 commit into
mainfrom
developer-guide-contribution-workflow

Conversation

@jklare

@jklare jklare commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

The developer guide only had a paragraph that pointed contributors to GitHub's pull request documentation. The rest of the process was spread over the style guide and the Zuul CI page, and some of it was not written down anywhere.

This PR replaces that paragraph with a Contribution workflow section in docs/guides/developer-guide/index.md. It lists six steps in order:

  1. Open an issue in the repository where the problem exists. Use osism/issues only if it is not yet clear which repository is affected, or if several repositories are affected.
  2. Create a branch: external contributors use a fork, OSISM team members push to the repository in the osism organization.
  3. Commit, following the commit message guidelines. This step also points out our rules for transparency about AI assistance: an AI-assisted change gets an Assisted-by trailer naming the assistant, and Signed-off-by, from the responsible person, stays the last line and is never used for an AI assistant. It links to the full rules in the style guide.
  4. Open a pull request against the default branch.
  5. Pass the CI checks, including the zuul label for long-running jobs. This step names the linters the checks run (ansible-lint, yamllint, flake8, python-black, mypy, hadolint, depending on the repository) and where their configuration files are. Whether to run them locally is left to the contributor.
  6. Review and merge: at least one OSISM maintainer approves, and that maintainer also merges. The section does not say when the merge happens, because that can depend on ongoing release processes.

The page intro said that the issue tracker is osism/issues and linked "open an issue" straight to osism/issues/issues/new. It now states the same rule as step 1. This also removes that link, which redirects visitors who aren't logged in to the GitHub login page.

The intro also says that we can only fix problems we know about, to encourage reporting issues even if they seem minor.

The steps link to the existing style guide and Zuul CI pages instead of repeating them. The linter list comes from the Zuul check pipelines of the OSISM repositories.

Testing

  • markdownlint, markdown-table-formatter and codespell (MegaLinter documentation v10 image) pass.
  • lychee finds 0 errors, including the #commit-messages, #attribution-for-ai-assisted-changes, #python and #the-zuul-label anchors.
  • The local Docusaurus build passes.

🤖 Generated with Claude Code

@jklare
jklare force-pushed the developer-guide-contribution-workflow branch from 3b08a43 to 20998c0 Compare November 19, 2026 09:57
@jklare
jklare requested a review from osfrickler November 19, 2026 09:59
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

✅⚠️MegaLinter analysis: Success with warnings

Descriptor Linter Files Fixed Errors Max errors Warnings Elapsed time
✅ ACTION actionlint 5 0 0 0.04s
✅ JSON jsonlint 4 0 0 0.06s
✅ JSON prettier 4 0 0 0.24s
✅ JSON v8r 4 0 0 5.27s
✅ MARKDOWN markdownlint 184 0 0 1.99s
✅ MARKDOWN markdown-table-formatter 184 0 0 0.23s
✅ REPOSITORY betterleaks yes no no 0.58s
✅ REPOSITORY checkov yes no no 11.4s
✅ REPOSITORY git_diff yes no no 0.05s
✅ REPOSITORY secretlint yes no no 1.04s
✅ REPOSITORY trufflehog yes no no 2.61s
✅ SPELL codespell 194 0 0 0.35s
⚠️ SPELL lychee 190 1 0 28.41s
✅ YAML prettier 6 0 0 0.29s
✅ YAML v8r 6 0 0 4.48s
✅ YAML yamllint 6 0 0 0.31s

Detailed Issues

⚠️ SPELL / lychee - 1 error
📝 Summary
---------------------
🔍 Total.........1302
🔗 Unique.........957
✅ Successful....1183
⏳ Timeouts.........2
🔀 Redirected.......1
👻 Excluded.......116
❓ Unknown..........0
🚫 Errors...........1
⛔ Unsupported......1

Errors in docs/guides/developer-guide/style-guide.md
[ERROR] https://wiki.openstack.org/wiki/GitCommitMessages (at 79:1) | Network unreachable. Check internet connection or VPN settings

Errors in docs/guides/user-guide/openstack/migration-vmware-esxi.md
[TIMEOUT] https://hystax.com/cloud-migration/ (at 15:1) | Request timed out

Errors in docs/guides/user-guide/openstack/openstackclient.md
[TIMEOUT] https://adam.younglogic.com/2022/03/generating-a-clouds-yaml-file/ (at 137:9) | Request timed out

Hint: Followed 1 redirect. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

  • Documentation: Custom Flavors
  • Command: npx mega-linter-runner@10.2.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,JSON_JSONLINT,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_BETTERLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,SPELL_CODESPELL,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

MegaLinter is provided by OX Security
Show us your support by starring ⭐ the repository

@jklare
jklare force-pushed the developer-guide-contribution-workflow branch 3 times, most recently from 9d8c439 to 7aac3b6 Compare November 19, 2026 10:13
The developer guide only had a paragraph that pointed contributors to
GitHub's pull request documentation. The rest of the process was spread
over the style guide (commit messages) and the Zuul CI page, and some
of it was not written down anywhere, such as where to branch, which
linters CI runs and who merges a pull request.

Replace that paragraph with a "Contribution workflow" section that
lists the steps in order:

1. Open an issue in the repository where the problem exists. Use
   osism/issues only if it is not yet clear which repository is
   affected, or if several repositories are affected.
2. Create a branch: external contributors use a fork, OSISM team
   members push to the repository in the osism organization.
3. Commit, following the commit message guidelines. This step also
   points out our rules for transparency about AI assistance: an
   AI-assisted change gets an Assisted-by trailer naming the
   assistant, and Signed-off-by, from the responsible person, stays
   the last line and is never used for an AI assistant. It links to
   the full rules in the style guide.
4. Open a pull request against the default branch.
5. Pass the CI checks, including the zuul label for long-running
   jobs. This step names the linters the checks run (ansible-lint,
   yamllint, flake8, python-black, mypy, hadolint, depending on the
   repository) and where their configuration files are. Whether to
   run them locally is left to the contributor.
6. Review and merge: at least one OSISM maintainer approves, and that
   maintainer also merges. The section does not say when the merge
   happens, because that can depend on ongoing release processes.

The steps link to the existing style guide and Zuul CI pages instead
of repeating them. The two GitHub documentation links now point to
their current URLs instead of the old ones that redirect.

The page intro said that the issue tracker is osism/issues and linked
"open an issue" straight to osism/issues/issues/new. Update it to the
same rule as step 1. This also removes that link, which redirects
visitors who are not logged in to the GitHub login page.

The intro also says that we can only fix problems we know about, to
encourage reporting issues even if they seem minor.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Jan Klare <klare@osism.tech>
@jklare
jklare force-pushed the developer-guide-contribution-workflow branch from 7aac3b6 to 379ccae Compare November 19, 2026 10:17

@osfrickler osfrickler left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

lgtm, waiting a bit with merging to give others a chance to give feedback, too

@osfrickler
osfrickler merged commit 66374fc into main Nov 19, 2026
5 checks passed
@osfrickler
osfrickler deleted the developer-guide-contribution-workflow branch November 19, 2026 14:31
@github-project-automation github-project-automation Bot moved this from New to Done in Human Board Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants