From 6b5f4d4ce4f1f6fc16cc30e23e93e92eb47b00ee Mon Sep 17 00:00:00 2001
From: VictoriaBeilstenEdmands <victoria.beilsten.edmands@gmail.com>
Date: Mon, 9 Mar 2026 11:43:01 +0000
Subject: [PATCH] Add contributing guide

---
 .github/ISSUE_TEMPLATE/bug_report.md |  45 ++++++
 .github/ISSUE_TEMPLATE/proposal.md   |  43 ++++++
 changelog.md                         |  82 +++++------
 contributing.md                      | 207 +++++++++++++++++++++++++++
 4 files changed, 337 insertions(+), 40 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/proposal.md
 create mode 100644 contributing.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..f897b26
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,45 @@
+---
+name: "Bug Report"
+about: Report a bug or unexpected behaviour
+type: bug
+labels: ["needs-triage"]
+---
+
+# Bug Report
+
+## Summary
+
+Briefly describe the problem.
+
+## Expected behaviour
+
+What should happen?
+
+## Actual behaviour
+
+What happens instead?
+
+## Steps to reproduce
+
+Provide clear, minimal steps:
+
+1.
+2.
+3.
+
+Include a **minimal reproduction** if possible.
+
+## Screenshots or visual evidence (if applicable)
+
+Include screenshots or recordings for visual issues.
+
+## Environment
+
+- Package version:
+- Browser:
+- OS:
+- App or framework environment (if relevant):
+
+## Additional context
+
+Anything else that might help understand or diagnose the issue.
diff --git a/.github/ISSUE_TEMPLATE/proposal.md b/.github/ISSUE_TEMPLATE/proposal.md
new file mode 100644
index 0000000..bb39827
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/proposal.md
@@ -0,0 +1,43 @@
+---
+name: "Change Proposal"
+about: Propose a change or new component (discussion required before PRs)
+labels: ["needs-triage"]
+---
+
+# Change Proposal: [Title]
+
+## What is being proposed?
+
+Briefly describe the change or new component.
+
+## Why is this needed?
+
+What problem does this solve?  
+What is missing or not working well today?
+
+## What will change?
+
+Does this affect:
+- Behaviour?
+- Component props or usage?
+- Introduce a new component?
+
+A short description is enough.
+
+## Interface changes (if any)
+
+If this changes how a component is used, briefly describe how.
+
+```ts
+// Optional sketch
+<MyComponent newProp="..." />
+```
+
+## Breaking change?
+
+- [ ] Yes
+- [ ] No
+
+## Next steps
+A maintainer will review this issue.
+If accepted, it will be marked as `accepted` and a PR may then be opened.
diff --git a/changelog.md b/changelog.md
index a31c735..d26432c 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,37 +1,35 @@
-SciReactUI Changelog
-====================
+# SciReactUI Changelog
 
-[v0.4.2] - unreleased
----------------------
+## [Unreleased]
 
 ### Fixed
 - Icon imports were causing issues downstream when components are unit tested.
 
-[v0.4.1] - 2026-02-24
----------------------
+
+## [v0.4.1] - 2026-02-24
 
 ### Fixed
-- *Progress* and *ProgressDelayed* where not exported
+- *Progress* and *ProgressDelayed* were not exported
 - Fix *User* login button having wrong colour
 
 ### Changed
 - The *NavMenu* will now close if something is selected.
 - Updated styles of *User* (style now similar to *NavMenu*)
 
-
-[v0.4.0] - 2026-02-10
----------------------
+## [v0.4.0] - 2026-02-10
 
 ### Added
+
 - New *Progress* component based on Diamond Light added.
 - New *ProgressDelayed* component so that the progress isn't shown at all when it's a small wait.
 - *NavMenu* component added for creating dropdown menus in the Navbar
   - *NavMenuLink* component extends NavLink to work in the NavMenu
 - *AuthProvider* added for authentication to Keycloak.
-  - An *auth* parameter was added to *User* to simplify when *AuthProvider* is used. 
+  - An *auth* parameter was added to *User* to simplify when *AuthProvider* is used.
 - *ScrollableImages* can now display in a wide view, with multiple images.
 
 ### Fixed
+
 - Hovering over a slot caused a popup with the slot title in. This has been removed.
 - Stopped Bar-based components (e.g. Navbar, Footer) from expanding when a parent component has a set height
 - The base *Bar* component was not being exported.
@@ -39,23 +37,24 @@ SciReactUI Changelog
 - *ScrollableImages* could attempt accessing images outside of array.
 
 ### Changed
+
 - *BaseTheme*/*DiamondTheme* secondary colour of dark theme has been much darkened. (You can select *DiamondOldTheme* if you prefer the older one!)
 - Remove first-child css selector as it causes problems with server-side rendering.
 
-
-[v0.3.0] - 2025-09-04
----------------------
+## [v0.3.0] - 2025-09-04
 
 ### Added
+
 - *Logo* component, to easily add the theme logo to anywhere
-- *ImageColourSchemeSwitch* takes a parameter *interchange* to swap image based on the opposite 
-of the colour scheme switch - for use with alternative background colours.
+- *ImageColourSchemeSwitch* takes a parameter *interchange* to swap image based on the opposite
+  of the colour scheme switch - for use with alternative background colours.
 - *BaseBar* component is the base for all the bars used in SciReactUI. Can also be used itself.
 - *AppBar* is a bar to show the main title of your App.
 - JsonForms renderers have been added for use with readonly mode in JsonForms.
 - Support for TIFFs in ScrollableImages component
 
 ### Fixed
+
 - Themes were not inheriting all details from their parents.
 - Fixed alt text on logos.
 - Fixed Footer was not adhering to Container width. (Can be turned off with containerWidth setting)
@@ -63,39 +62,41 @@ of the colour scheme switch - for use with alternative background colours.
 - Ordering of StoryBook now more intuitive.
 
 ### Changed
-- Breaking change: The use of *color* has been replaced with *colour* throughout. 
-  - *ImageColorSchemeSwitch*, *ImageColorSchemeSwitchType* and *ImageColorSchemeSwitchProps* 
-  renamed to *ImageColourSchemeSwitch*, ImageColourSchemeSwitchType and ImageColourSchemeSwitchProps respectively 
-  - *User* component color prop renamed to colour.
-- RootProps on *Breadcrumbs* has been removed. There props can be passed in directly. 
-e.g. `<Breadcrumbs sx={{color:"red"}} />` instead of `<Breadcrumbs rootProps={{sx: { color: "red" } }}/>` 
 
+- Breaking change: The use of *color* has been replaced with *colour* throughout.
+  - *ImageColorSchemeSwitch*, *ImageColorSchemeSwitchType* and *ImageColorSchemeSwitchProps*
+    renamed to *ImageColourSchemeSwitch*, ImageColourSchemeSwitchType and ImageColourSchemeSwitchProps respectively
+  - *User* component color prop renamed to colour.
+- RootProps on *Breadcrumbs* has been removed. There props can be passed in directly.
+  e.g. `<Breadcrumbs sx={{color:"red"}} />` instead of `<Breadcrumbs rootProps={{sx: { color: "red" } }}/>`
 
-[v0.2.0] - 2025-06-11
----------------------
+## [v0.2.0] - 2025-06-11
 
 ### Fixed
+
 - Styles added to Navbar and Footer incorrectly remove built in styles.
 - Logo not appearing when no dark src set in dark mode.
 
 ### Changed
-- Breadcrumbs component takes optional linkComponent prop for page routing. 
+
+- Breadcrumbs component takes optional linkComponent prop for page routing.
 - Navbar, NavLink and FooterLink will use routing library for links if provided with linkComponent and to props.
 - Navbar uses slots for positioning elements. Breaking change: elements must now use rightSlot for positioning to the far right.
 - User can take additional menu items through the menuItems prop.
 - Footer uses slots for positioning elements. Breaking change: elements must now use rightSlot for positioning to the far right.
 
 ### Added
-- ScrollableImages component to scroll through multiple images.
 
+- ScrollableImages component to scroll through multiple images.
 
-[v0.1.0] - 2025-04-10
----------------------
+## [v0.1.0] - 2025-04-10
 
 ### Added
+
 - Breadcrumbs take object array (CustomLink) for total control over names and links.
 
 ### Fixed
+
 - Stopped flicker between colour modes when starting an app in dark mode.
 - Footer links stopped from moving on hover when only showing links.
 - Footer links now correctly center horizontally, if needed.
@@ -103,29 +104,29 @@ e.g. `<Breadcrumbs sx={{color:"red"}} />` instead of `<Breadcrumbs rootProps={{s
 - User hides id and name when on very small screens
 
 ### Changed
-- Footer links now align with copyright when there is no logo.
 
+- Footer links now align with copyright when there is no logo.
 
-[v0.0.3] - 2025-01-27
---------------------
+## [v0.0.3] - 2025-01-27
 
 ### Fixed
+
 - Moved unnecessary build dependencies to devDependencies
 
 ### Changed
-- Return key now submits VisitInput (but that can be turned off).
 
+- Return key now submits VisitInput (but that can be turned off).
 
-[v0.0.2] - 2025-01-20
---------------------
+## [v0.0.2] - 2025-01-20
 
 ### Fixed
+
 - Not importing correctly in some external projects.
 
+## [v0.0.1] - 2024-12-19
 
-[v0.0.1] - 2024-12-19
---------------------
 ### Added
+
 - Components added:
   - Breadcrumbs - Highlight position of page in hierarchy
   - ColourSchemeButton - Switch between light and dark schemes.
@@ -143,14 +144,15 @@ e.g. `<Breadcrumbs sx={{color:"red"}} />` instead of `<Breadcrumbs rootProps={{s
   - Diamond
   - Generic
 
-[vUnreleased] - ????-??-??
---------------------------
+## [v0.0.0-alpha.1] - 2026-??-??
 
 ### Added
-- 
+
+-
 
 ### Fixed
-- 
+
+-
 
 ### Changed
 -
diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..fa7d2cc
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,207 @@
+# Contributing to sci-react-ui
+
+Thanks for your interest in contributing! We’re working together to build high‑quality, accessible, and consistent React components for scientific UIs. We encourage early discussion and aim to keep a high bar for quality, reliability, and accessibility. Wherever possible, we prefer using existing MUI components instead of building custom ones.
+
+**TLDR**
+- Start with a GitHub issue.
+- Wait for the issue to be accepted by a maintainer before opening a PR.
+- Be clear about *what* you are changing and *why*.
+
+---
+
+## Core Principles
+
+- **Discussion before code**: agree on approach early.
+- **Quality matters**: accessibility, tests, and docs are expected.
+- **Clarity**: explain purpose, behaviour, and interfaces plainly.
+- **Stability**: changes should be predictable for consumers.
+- **Reuse over reinvention**: prefer MUI components and patterns over custom implementations.
+
+---
+
+## Contribution Flow
+
+1. **Open a GitHub Issue**
+   - Ideally, open an issue before writing any code.
+   - Describe the change or addition.
+   - Explain *why* it is needed.
+   - Describe expected behaviour and appearance.
+
+2. **Maintainer Review**
+   - A maintainer reviews the issue.
+   - If accepted, it will be labeled `accepted`.
+
+3. **Open a Pull Request**
+   - Only after the issue is accepted.
+   - The PR must address the accepted issue.
+   - Include appropriate tests, stories, docs, and a changelog entry where relevant.
+
+4. **Approval and Merge**
+   - Once approved and CI passes, the PR can be merged.
+
+---
+
+## Issues
+
+Issues are required for **all contributions**.
+
+We provide GitHub issue templates to help structure discussion:
+
+- [Change Proposal](.github/ISSUE_TEMPLATE/change-proposal.md) for proposing changes, enhancements, or new components
+- [Bug Report](.github/ISSUE_TEMPLATE/bug-report.md) for reporting bugs or unexpected behaviour
+
+Using a template is recommended but not required.
+
+### Bug Reports
+
+Include:
+- What is broken
+- Expected vs actual behaviour
+- Steps to reproduce
+- Environment details (browser, OS, version if relevant)
+
+### Updating an Existing Component
+
+Include:
+- **Why** the change is needed (bug fix, improvement, behaviour change)
+- Any **API or interface changes**
+- Potential impact on existing usage
+
+### New Components
+
+Include:
+- **Purpose**: the problem the component solves
+- **Why it belongs in this library**
+- A clear description of the **interface**
+- Any accessibility considerations
+
+Designs or sketches are welcome if they help with explanation.
+
+### Other Changes (Documentation, Tooling, Chores)
+
+For changes that do **not** affect component behaviour or APIs (for example documentation updates, tooling, or CI improvements):
+
+- Open a GitHub issue describing the change and motivation.
+- A maintainer must still accept the issue before a PR is opened.
+- Keep PRs small and focused.
+- Tests and changelog entries are not required unless behaviour is affected.
+
+---
+
+## Pull Requests
+
+### Requirements
+
+- Reference the accepted issue.
+- Clearly describe the change and its motivation, including any API or behaviour differences.
+- Add or update tests where behaviour changes.
+- Maintain accessibility and keyboard support.
+
+Expected in PRs:
+- Unit and accessibility tests
+- Storybook stories (states and variants)
+- Documentation updates
+- Changelog entry
+- Screenshots for UI changes
+
+No commented‑out code or TODOs.
+
+### Review & Merging
+
+- CI must pass.
+- Maintainer approval is required.
+- All review comments must be resolved.
+
+---
+
+## Design & Accessibility
+
+- Use semantic HTML and ARIA where appropriate.
+- Follow existing accessibility and interaction patterns.
+- Avoid unnecessary complexity or abstraction.
+- Support `className` and `style` passthrough.
+- Keep modules small and tree‑shakable.
+- Use British English
+
+---
+
+## Storybook
+Each component should include:
+   - `<component-name>.stories.tsx` with example controls
+   - Stories covering common states and edge cases (e.g. default, disabled, focus, error, loading). 
+
+---
+
+## API & Breaking Changes
+
+- Prefer additive changes.
+- Breaking or user‑visible changes must be clearly stated in:
+  - The issue
+  - The PR description
+- Migration notes are appreciated when relevant.
+- For breaking changes:
+  - Label `breaking-change`
+  - Provide migration notes
+  - Update changelog
+
+---
+
+## Versioning & Changelog
+
+- **SemVer**: `MAJOR.MINOR.PATCH`.
+- Maintain `CHANGELOG.md` (Keep-a-Changelog style).
+- Each PR that changes behavior should add a changelog entry under **Unreleased**:
+  - Added / Changed / Deprecated / Removed / Fixed / Security
+- Releases promote **Unreleased** to a dated version section.
+
+### Alpha & Beta Releases
+
+We may publish **pre‑release versions** to gather feedback before a stable release:
+
+- **Alpha (`x.y.z-alpha.n`)**
+  - Early, incomplete, or experimental features
+  - APIs and behaviour may change without notice
+  - Not recommended for production use
+
+- **Beta (`x.y.z-beta.n`)**
+  - Features may still be under validation
+  - APIs should be mostly stable, but changes are still possible
+  - Intended for early adopters and testing
+
+Pre‑release versions do not require the same stability guarantees as stable releases, and changes between pre‑releases may be breaking.
+
+---
+
+## Code Style & Tooling
+
+- TypeScript strict mode
+- ESLint and Prettier
+- Conventional commits (`feat(Button): add aria-expanded`)
+- Co‑locate tests and stories
+- Do not add unnecessary dependencies
+- Branch naming: `initials/short-description`
+
+---
+
+## AI‑Assisted Contributions
+
+AI may assist, but contributors are responsible for correctness.
+
+- Understand every line submitted
+- No unverifiable AI-generated content
+- Never include prompts
+
+---
+
+## Security
+
+- Never commit secrets or credentials.
+- Report vulnerabilities privately to maintainers.
+
+---
+
+## Final Notes
+
+If you are unsure whether a change belongs here, **open an issue and ask**. Early discussion is strongly preferred.
+
+Thanks for contributing
\ No newline at end of file