logo

Contributing

The Smart Cities SIG is a collaborative ecosystem initiative that brings together municipalities, industry participants, academia, standards organizations, and other stakeholders to address practical smart city interoperability challenges and develop reusable outputs.

Before Contributing

Before contributing, participants are encouraged to review the following documents:

These documents explain the purpose of the initiative, participation expectations, collaboration model, and the methodology used to analyze interoperability challenges and develop Smart City Profiles.

What Can You Contribute?

The Smart Cities SIG welcomes contributions from municipalities, public agencies, utilities, technology providers, standards organizations, academic institutions, and other ecosystem stakeholders.

Examples of contributions include:

  • Municipal requirements
  • Business and operational use cases
  • Interoperability challenges
  • Existing standards and specifications
  • Semantic models and data models
  • Gap analyses
  • Workshop outputs
  • Profile reviews
  • Proof of Concept participation
  • Implementation experience and lessons learned
  • Supporting reports and reference material

Participants are encouraged to contribute practical knowledge and real-world experience that can help improve interoperability across smart city ecosystems.

What Makes a Good Contribution?

The most effective contributions are:

  • based on real-world experience,
  • clearly describe a problem or opportunity,
  • identify affected stakeholders,
  • reference existing standards or practices when known,
  • contribute to interoperability,
  • and help advance reusable Smart Cities SIG outputs.

What Not to Contribute

To support open and reusable collaboration, contributors should avoid submitting:

  • confidential or non-public information,
  • proprietary material that cannot be openly shared,
  • content subject to licensing restrictions incompatible with the repository license,
  • promotional or marketing material unrelated to the objectives of the Smart Cities SIG,
  • duplicate content that does not advance ongoing discussions,
  • and material unrelated to smart city interoperability challenges or Smart Cities SIG activities.

Questions regarding contribution suitability may be raised through GitHub Issues or with SIG coordinators before submitting content.

Participation Levels

Participants may engage with the Smart Cities SIG in different ways.

Observer

Observers may:

  • follow repository activities,
  • review published materials,
  • attend meetings,
  • and monitor ongoing work.

Contributor

Contributors may:

  • create GitHub Issues,
  • participate in discussions,
  • provide feedback,
  • review outputs,
  • and contribute supporting material.

Active Contributor

Active Contributors may:

  • develop content,
  • submit Pull Requests,
  • lead work items,
  • coordinate profile activities,
  • and participate in Proof of Concept initiatives.

Repository-First Contribution Model

The Smart Cities SIG follows a repository-first collaboration model.

Contributors are encouraged to create Issues, share ideas, raise questions, and propose improvements as soon as they are identified.

Contributions do not need to wait for a scheduled meeting.

Monthly meetings are intended to support coordination, review progress, discuss challenges, and align participants. The repository remains the primary location for collaboration, discussion, and traceability.

Typical Contribution Flow

Most contributions follow a simple workflow:

  1. Identify a requirement, use case, interoperability challenge, or improvement opportunity.
  2. Create or join a GitHub Issue.
  3. Discuss and refine the proposal with other participants.
  4. Develop supporting content when appropriate.
  5. Submit proposed changes through a Pull Request.
  6. Participate in review and feedback activities.
  7. Incorporate agreed changes and publish the resulting output.

Not all contributions require all steps. The workflow should remain practical and proportional to the scope of the contribution.

Contribution Paths

Choose the contribution path that best matches your input.

GitHub Issue

Use an Issue when:

  • proposing a new idea,
  • identifying a requirement,
  • raising an interoperability gap,
  • requesting clarification,
  • sharing implementation experience,
  • reporting a concern,
  • or starting a discussion.

When creating a new Issue, contributors are encouraged to provide:

  • a clear description of the problem or opportunity,
  • relevant stakeholders,
  • existing standards or specifications (if known),
  • expected benefits,
  • and supporting references where available.

Pull Request

Use a Pull Request when:

  • proposing changes to repository content,
  • updating existing material,
  • adding agreed content,
  • correcting errors,
  • or contributing content ready for review.

Pull Requests should:

  • focus on a specific topic,
  • remain reasonably scoped,
  • include sufficient context for reviewers,
  • reference related Issues when appropriate,
  • and reflect prior discussions whenever practical.

Supporting Documents

Supporting documents may be used for:

  • workshop outputs,
  • presentations,
  • reports,
  • background analysis,
  • requirements gathering,
  • use case documentation,
  • and reference material.

Supporting documents should follow the repository practices described below.

Municipal Contributions

Municipalities play a central role in the Smart Cities SIG.

Municipal participants are encouraged to contribute:

  • operational requirements,
  • business challenges,
  • use cases,
  • implementation experience,
  • lessons learned,
  • and validation feedback.

Municipal participants are not expected to be standards experts in order to contribute effectively.

Standards and Ecosystem Contributions

Standards organizations, industry alliances, research institutions, and related ecosystem initiatives are encouraged to contribute:

  • existing specifications,
  • data models,
  • interoperability approaches,
  • implementation guidance,
  • and lessons learned.

The Smart Cities SIG seeks alignment and reuse wherever practical.

Contribution Workflow

Branches

Contributors with repository write access should create feature branches for proposed changes.

Protected branches may only be updated through Pull Requests.

Pull Requests

Pull Requests may be reviewed by initiative maintainers, coordinators, subject matter experts, and other contributors.

Contributors should be prepared to refine and improve submissions based on review feedback.

Reviews

Reviews are intended to improve the quality, accuracy, clarity, and reusability of Smart Cities SIG outputs.

Feedback should remain constructive, practical, and focused on the contribution itself.

Repository Practices

File Naming

Supporting documents, presentations, reports, proposals, and meeting-related artifacts should use the following date-prefixed format:

YYYYMMDD-description.ext

Examples:

20260521-smart-lighting-workshop.md
20260603-water-use-case-analysis.pptx

Repository Structure

Contributors are encouraged to follow the repository organization guidelines defined in:

Repository Structure

New folders and content structures should only be introduced when necessary and should align with the existing repository organization model.

Questions and Support

Questions regarding contributions, repository practices, work items, or collaboration activities may be raised through:

  • GitHub Issues,
  • Smart Cities SIG meetings,
  • Groups.io discussions,
  • or designated SIG coordinators.

Participants are encouraged to ask questions early and collaborate openly.

Thank You

Thank you for helping improve smart city interoperability through open collaboration, practical experience, and reusable ecosystem outputs.