Skip to content

README: Modernise top-level README.md#490

Open
ArokyaMatthew wants to merge 1 commit intoeclipse-basyx:developfrom
ArokyaMatthew:feature/modernise-readme-475-v2
Open

README: Modernise top-level README.md#490
ArokyaMatthew wants to merge 1 commit intoeclipse-basyx:developfrom
ArokyaMatthew:feature/modernise-readme-475-v2

Conversation

@ArokyaMatthew
Copy link
Copy Markdown

Description

Rewrites the top-level README to give new visitors a clearer picture of what this project does, which specifications it implements, and where to find things.

This is a revised version of #488, rebased onto develop and updated with all review feedback from @s-heppner.

Changes from v1 (#488), addressing review feedback

  • Specification compliance moved to the top — this is what AAS tool developers look for first. Kept as a table (badges would be overwhelming for five spec rows).
  • Removed the "Details" column from the package overview table — the directory links in the first column already serve that purpose.
  • Removed "Compliance Checking" bullet from the SDK feature list — that's now the Compliance Tool's responsibility, not the core SDK.
  • Updated server interfaces to include Registry and Discovery APIs, reflecting the current state of develop (Experimental/registry and discovery server #407).
  • Removed the "Getting Started" section entirely — it duplicated content from the sub-package READMEs and would be hard to keep in sync.
  • Trimmed the FAQ — removed the Python-version question (will go stale), removed the SDK-vs-spec-version question (already covered by the note above), and removed the Conda question (already linked in the badges). Added the suggested interoperability FAQ about strict spec compliance and the Compliance Tool.
  • Updated the Release Schedule to reflect the actual workflow: development happens on develop, only published states are merged to main.
  • PR now targets develop instead of main.

What's in the new README

  • Status badges (CI, PyPI, Conda, downloads, Python versions, license)
  • Brief introduction and link to Eclipse BaSyx
  • Specification compliance table (first content section)
  • Table of contents
  • Project overview with package summary table and per-package descriptions
  • Repository structure (ASCII tree)
  • Tutorials table linking all six SDK tutorials
  • Read the Docs link
  • FAQ (interoperability question + server-without-Docker)
  • Release schedule
  • Contributing section with ECA link
  • License

Fixes #475
Supersedes #488

The top-level README was sparse compared to other Eclipse BaSyx
repositories. This commit rewrites it with structured sections,
status badges, specification compliance table (moved to the top),
updated server description (Registry and Discovery APIs), tutorials,
FAQ, and corrected release schedule reflecting the develop workflow.

Changes based on review feedback:
- Removed 'Details' column from package overview table
- Removed 'Compliance Checking' from SDK features (now a separate package)
- Updated server interfaces to include Registry and Discovery APIs
- Moved specification compliance to the top of the file
- Removed 'Getting Started' section (duplicates sub-package READMEs)
- Trimmed FAQ to genuinely asked questions
- Updated release schedule to reflect develop-to-main workflow

Fixes eclipse-basyx#475
@ArokyaMatthew ArokyaMatthew force-pushed the feature/modernise-readme-475-v2 branch from 7940734 to 3a14055 Compare May 1, 2026 05:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant