Skip to content
This repository was archived by the owner on Apr 7, 2025. It is now read-only.

Commit e5bb853

Browse files
AleksandarColeAleksandarCole
committed
Adding API SIG and RFC instructions.
1 parent 11bb747 commit e5bb853

File tree

7 files changed

+291
-2
lines changed

7 files changed

+291
-2
lines changed

‎docs/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,10 @@ Contributors list is WIP
2424

2525
Documentation team meets weekly. Meeting agenda is always published one week prior. All contributors are welcome, open an issue to join the SIG and get a calendar invite.
2626

27-
- 💬 [Join the Discord channel](#)
27+
- 💬 [Join the Discord channel](https://discord.gg/Rvum6crB6z)
2828
- 📆 Every `Monday` at `1pm UTC`
2929
- 📝 [Meeting minutes](https://github.com/semaphoreci/semaphore/blob/main/docs/docs-contributing/meeting-notes.md)
30-
- 🙋‍♂️ [Join the SIG](https://github.com/semaphoreci/semaphore/issues/new?assignees=TomFern%2CAleksandarCole&labels=documentation&projects=semaphoreci%2F2&template=DOCS_ISSUE.yml&title=%5BDocs%5D%3A%20Workgroup%20request+) < select `Join the SIG` from the dropdown.
30+
- 🙋‍♂️ [Join the SIG](https://forms.gle/tcNpGA4Zyghnu7sh8) < select `SIG - Docummentation` when filling in form.
3131

3232
## License
3333

‎rfcs/.DS_Store

6 KB
Binary file not shown.

‎rfcs/0000-example/rfc.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Title
2+
3+
[RFC 0000 - short descriptive name]
4+
5+
## What
6+
7+
[Provide a brief summary of the proposed change or feature. This should be a concise description of what is being proposed, giving readers a quick understanding of the RFC's purpose.]
8+
9+
## Why
10+
11+
[Explain the motivation behind this RFC. Describe the problem it aims to solve or the improvement it seeks to make. Include context about why this change is important and how it aligns with Semaphore's goals.]
12+
13+
## Solution details
14+
15+
[Provide a detailed description of the proposed solution. This section should be comprehensive, covering all aspects of the proposal. You may use the subsections below to organize your thoughts, but feel free to adjust as needed for your specific RFC.]
16+
17+
### Functionality
18+
19+
[Offer a detailed functionality specification explaining how the feature works. Include user interactions, system behaviors, and any new concepts introduced.]
20+
21+
### Architecture
22+
23+
[Describe the architectural changes or additions required to implement this proposal. Include diagrams if they would be helpful.]
24+
25+
### UI/UX design
26+
27+
[If applicable, provide proposals for UI patterns and design. Include mockups or wireframes if available.]
28+
29+
## Open questions
30+
31+
[List any unresolved issues, areas where you're seeking input, or aspects of the proposal that require further discussion. Frame these as questions to encourage specific feedback from collaborators.]
32+
33+
- Question 1?
34+
- Question 2?
35+
- Question 3?

‎rfcs/README.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Semaphore RFCs (Requests for Comments)
2+
3+
## Introduction
4+
5+
This document outlines the RFC (Request for Comments) process for the Semaphore updates. It is a way for the Semaphore team to include the community and users in the discussion and design of future improvements.
6+
7+
RFCs are design documents used to propose, describe, and discuss significant changes to Semaphore. The RFC process provides a structured way to gather input from the community and users before implementing major features or changes.
8+
9+
## When should an RFC be created?
10+
11+
An RFC should be created for any substantial change to Semaphore that would benefit from broader discussion and consensus. This includes, but is not limited to:
12+
13+
- New features with significant impact on users or the architecture
14+
- Major changes to existing features or APIs
15+
- Introduction of new integrations with the Semaphore
16+
17+
Not every change will be covered by an RFC. RFCs serve to efficiently gather improvement ideas from the community and validate existing proposals through community feedback.
18+
19+
## How to create an RFC
20+
21+
1. Fork the Semaphore repository.
22+
23+
2. Create a new branch named `rfc/short-descriptive-title`. For example: `rfc/new-user-api`.
24+
25+
3. Create a new subfolder in the `rfcs` directory with the format `0000-your-feature`. For example: `rfcs/0000-new-user-api/`.
26+
27+
4. Copy the RFC template from `rfcs/0000-example/rfc.md` to your new subfolder, naming it `rfc.md`.
28+
29+
5. Fill in the RFC template with your proposal. Be as detailed as possible, including motivation, design details, alternatives considered, and potential drawbacks.
30+
31+
6. Submit a pull request to the Semaphore repository with your RFC.
32+
33+
7. Update the front matter of your RFC:
34+
- Assign yourself as the author
35+
- Set the status to "Draft"
36+
- Leave the RFC number as 0000 (it will be assigned later)
37+
38+
8. The pull request description should include a brief summary of the RFC and any additional context that might be helpful for reviewers.
39+
40+
## How are RFCs reviewed?
41+
42+
1. Once submitted, Semaphore team will assign a number to the RFC and update the folder name accordingly.
43+
44+
2. The community and Semaphore team will review the RFC, asking questions and providing feedback through pull request comments.
45+
46+
3. You should be prepared to revise your RFC based on the feedback received. Push your changes to the same branch to update the pull request.
47+
48+
4. RFCs must remain in the "Draft" status for a minimum of **two weeks** to allow sufficient time for review and discussion.
49+
50+
5. After the review period, Semaphore team will decide to either:
51+
- Accept the RFC and merge the pull request
52+
- Request further changes
53+
- Decline the RFC and close the pull request
54+
55+
6. Accepted RFCs will have their status updated to "Accepted" before merging and a number assigned.
56+
57+
## Implementation
58+
59+
Once an RFC is accepted:
60+
61+
1. The Semaphore team can begin implementation work.
62+
63+
2. Create a new issue in the Semaphore repository to track the implementation progress, linking back to the RFC.
64+
65+
3. The issue is to be used only to communicate the progress to community and users.
66+
67+
4. The proper **internal** project has to be set up to coordinate implementation on Semaphore team side.
68+
69+
5. Once the implementation is complete and merged, Semaphore team will update the RFC's status to "Implemented" and move it to the `archive` folder.
70+
71+
## End of life
72+
73+
As Semaphore evolves, some RFCs may become obsolete or be superseded by newer proposals. In such cases:
74+
75+
1. Create a pull request to update the RFC's status to "Deprecated" and move it to the `archive` folder.
76+
77+
2. In the PR, provide a brief explanation of why the RFC is being deprecated and, if applicable, link to any new RFCs or documentation that replace it.
78+
79+
3. Once approved and merged, the RFC will be clearly marked as deprecated but will remain in the repository for historical context.
80+
81+
Remember, the RFC process is meant to be collaborative and iterative. Don't hesitate to ask for help or clarification throughout the process. Your contributions help shape the future of Semaphore!

‎sigs/README.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Semaphore Special Interest Groups (SIGs)
2+
3+
## Introduction
4+
5+
Special Interest Groups (SIGs) are designed to foster collaboration between the Semaphore team, community members, and users. The primary purpose of SIGs is to:
6+
7+
1. Enable community members and users to actively participate in the Semaphore design
8+
2. Provide a platform for sharing experiences and use-cases
9+
3. Allow participants to help shape specific product areas
10+
4. Influence the development and direction of these product areas
11+
12+
By joining a SIG, you have the opportunity to contribute your expertise, insights, and real-world experiences to help improve Semaphore. Whether you're a long-time user, a new community member, or someone with a unique perspective on a particular aspect of Semaphore, your input is valuable in driving it forward.
13+
14+
SIGs serve as a bridge between the core Semaphore team and the wider community, ensuring that development is aligned with user needs and industry trends.
15+
16+
## Current SIGs
17+
18+
Semaphore currently has several active Special Interest Groups, each focusing on a specific area of the product. These SIGs are open for anyone to join and contribute to with the approval of sig owner. Below is a list of our current SIGs, their purposes, owners, and links to their respective spaces.
19+
20+
| Name | Purpose | Owners | Link to SIG Space |
21+
|------|---------|--------|-------------------|
22+
| SIG-API and extensibility| Focuses on API development, and explores venues of extending Semaphore with various integrations | @radwo | [SIG-API Space](./api-and-extensibility/README.md) |
23+
| SIG-Documentation | Ensures comprehensive and up-to-date Semaphore documentation | @TomFern | [SIG-Documentation Space](../docs/README.md) |
24+
25+
Each SIG meets regularly to discuss ongoing projects, address challenges, and plan future developments. We encourage you to explore these SIGs and join the ones that align with your interests or expertise.
26+
27+
### Future SIGs
28+
29+
As Semaphore continues to grow and evolve, we plan to expand our range of Special Interest Groups.
30+
31+
Here are some SIGs we're planning to establish in the near future:
32+
33+
- **SIG-Agents**: This group will focus on Semaphore self-hosted agents, working to improve their functionality, performance, and user experience.
34+
- **SIG-Tests**: Dedicated to enhancing Semaphore's test reporting capabilities, this group will work on developing and refining test report parsers for various technology stacks.
35+
36+
If you're interested in these upcoming SIGs or have ideas for additional groups, we encourage you to reach out to the Semaphore team.
37+
38+
## How SIGs Operate
39+
40+
Special Interest Groups in Semaphore operate with a focus on collaboration, transparency, and community involvement. Here's an overview of how SIGs function:
41+
42+
### Regular Meetings
43+
44+
1. **Frequency**: SIGs typically meet on a regular schedule, often weekly or monthly.
45+
2. **Format**: Meetings are usually held via video conference to accommodate global participation.
46+
3. **Agenda**: Each meeting has a predefined agenda, which is shared in advance for input and preparation.
47+
4. **Minutes**: Detailed minutes are taken and shared publicly to keep the wider community informed.
48+
49+
### Communication Channels
50+
51+
1. **Discord Channel**: Each SIG has a dedicated Discord channel for ongoing discussions and quick communications.
52+
2. **GitHub Discussions**: For technical discussions and proposals, SIGs use GitHub Discussions within the Semaphore repository.
53+
3. **RFCs**: For more in-depth collaboration on proposal, SIGs use [RFCs](../rfcs/README.md).
54+
55+
### Decision Making
56+
57+
1. **Consensus-based**: SIGs strive for consensus in decision-making.
58+
2. **Ownership**: When consensus cannot be reached, final decisions are left at the discression of SIG owner.
59+
3. **Transparency**: All significant decisions are documented and shared with the broader community.
60+
61+
### Deliverables
62+
63+
1. **Proposals**: SIGs develop and refine proposals for new features or significant changes.
64+
2. **Documentation**: SIGs are responsible for maintaining documentation related to their focus area.
65+
66+
### Reporting
67+
68+
1. **Regular Updates**: SIGs provide updates to the broader Semaphore community on their progress and plans.
69+
2. **Annual Review**: Each SIG conducts an annual review of its activities, achievements, and future goals.
70+
71+
### Community Engagement
72+
73+
1. **Open Participation**: SIG meetings and discussions are open to all interested parties.
74+
2. **Mentorship**: Experienced SIG members often mentor newcomers to help them contribute effectively.
75+
3. **Cross-SIG Collaboration**: SIGs collaborate with each other on overlapping or interdependent initiatives.
76+
77+
By operating in this structured yet flexible manner, SIGs can effectively drive progress in their focus areas while ensuring community involvement and transparency. This approach allows Semaphore to benefit from diverse perspectives and expertise, leading to better outcomes as a whole.
78+
79+
## Joining a SIG
80+
81+
Joining a Special Interest Group is a great way to contribute to Semaphore and collaborate with others who share your interests. Here's how you can get involved:
82+
83+
1. **Choose a SIG**:
84+
- Review the list of current SIGs in the [Current SIGs](#current-sigs) section above.
85+
- Select a SIG that aligns with your interests or expertise.
86+
87+
2. **Join the Communication Channels**:
88+
- Join the SIG's Discord channel (listed in the SIG's space).
89+
90+
3. **Attend a Meeting**:
91+
- Check the SIG's calendar for upcoming meetings (found in the SIG's space).
92+
- Attend a meeting as an observer to get a feel for the group's dynamics and current projects.
93+
- Introduce yourself during the meeting when appropriate.
94+
95+
4. **Review Current Work**:
96+
- Look at the SIG's **Ongoing** section to understand ongoing work.
97+
- Read through recent meeting minutes to catch up on discussions and decisions.
98+
99+
5. **Start Contributing**:
100+
- Participate in discussions on Discord or GitHub.
101+
- Offer to help with documentation, code reviews, or testing.
102+
103+
6. **Engage Regularly**:
104+
- Attend meetings consistently to stay involved in discussions and decision-making.
105+
- Contribute your ideas and feedback on ongoing projects.
106+
107+
Remember, you're welcome to join multiple SIGs if you're interested in various aspects of Semaphore. Each SIG may have slightly different norms and processes, so don't hesitate to ask questions and seek guidance from more experienced members.
108+
109+
If you're new to Semaphore, joining a SIG is an excellent way to learn and grow while making meaningful contributions. Welcome aboard!

‎sigs/api-and-extensibility/README.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# SIG - API and extensibility
2+
3+
The API and Extensibility Special Interest Group is dedicated to improving and expanding Semaphore's API capabilities and its integration ecosystem. This SIG plays a crucial role in ensuring that Semaphore remains flexible, powerful, and developer-friendly.
4+
5+
**Key Focus Areas:**
6+
7+
1. **API Development:** Enhancing and maintaining Semaphore's API to support a wide range of use cases.
8+
2. **Extensibility:** Developing and improving integrations with other tools and platforms.
9+
3. **Developer Experience:** Ensuring the API and integrations are intuitive and well-documented.
10+
11+
**Goals:**
12+
13+
- Source feedback from the community and users on API and integration needs.
14+
- Align API and extensibility development with real-world developer requirements.
15+
- Improve documentation and resources for API users and integration developers.
16+
- Identify and prioritize new integration opportunities.
17+
18+
We welcome contributions from API enthusiasts, integration specialists, and anyone interested in improving how Semaphore connects with other tools in the development pipeline.
19+
20+
## SIG meetings
21+
22+
Documentation team meets weekly. Meeting agenda is always published one week prior. All contributors are welcome, open an issue to join the SIG and get a calendar invite.
23+
24+
- 💬 [Join the Discord channel](https://discord.gg/w27XA4tUaX)
25+
- 📆 Every `Thursday` at `2pm UTC`
26+
- 📝 [Meeting minutes](./meeting-minutes.md)
27+
- 🙋‍♂️ [Join the SIG](https://forms.gle/tcNpGA4Zyghnu7sh8)
28+
29+
## Ongoing work
30+
31+
### API v2
32+
33+
This SIG is currently working on designing the new version of Semaphore API and setting up the updated API design guidelines.
34+
35+
**Resouces:**
36+
37+
- [API v2 RFD](#)
38+
- [API v2 RFC](#)
39+
40+
## Top Contributors
41+
42+
Contributors list is WIP

‎sigs/api-and-extensibility/meeting-minutes.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# API and extensibility SIG meeting minutes
2+
3+
## 03-October-2024
4+
5+
### Attendees
6+
7+
- @radwo
8+
- @hamir-suspect
9+
- @darkofabijan
10+
- @lucaspin
11+
- @DamjanBecirovic
12+
- @lucianoliberti
13+
14+
### Agenda
15+
16+
- Review the proposed changes to existing endpoints
17+
- Review the proposed changes to API Design Gudeline
18+
- Discuss any open questions
19+
20+
### Notes
21+
22+
To be added by @radwo after the meeting.

0 commit comments

Comments
 (0)