|
1 | | -# Contributing to Sparxstar & Starmus Projects |
| 1 | +# Contributing Guide |
2 | 2 |
|
3 | | -First off, thank you for considering a contribution. Your expertise is valued, and your efforts help us build a better, more resilient platform. |
| 3 | +Thank you for contributing to SPARXSTAR User Environment Check. |
4 | 4 |
|
5 | | -This document provides a set of guidelines for contributing to this repository. These are mostly guidelines, not strict rules. Use your best judgment, and feel free to propose changes to this document in a pull request. |
| 5 | +## Access Model |
6 | 6 |
|
7 | | -**Important Note:** This is a private, managed repository. Contributions are welcome from team members and invited collaborators only. We do not accept unsolicited pull requests from the general public. If you believe you have found a security vulnerability, please follow our [Security Policy](#security-vulnerability-reporting). |
| 7 | +This is a managed/private repository. Contributions are accepted from authorized team members and approved collaborators. |
8 | 8 |
|
9 | | -## Table of Contents |
| 9 | +## Contribution Rules |
10 | 10 |
|
11 | | -- [Code of Conduct](#code-of-conduct) |
12 | | -- [How Can I Contribute?](#how-can-i-contribute) |
13 | | - - [Reporting Bugs](#reporting-bugs) |
14 | | - - [Suggesting Enhancements](#suggesting-enhancements) |
15 | | - - [Your First Code Contribution](#your-first-code-contribution) |
16 | | -- [Development Setup](#development-setup) |
17 | | -- [Style Guides](#style-guides) |
18 | | - - [Git Commit Messages](#git-commit-messages) |
19 | | - - [JavaScript Style Guide](#javascript-style-guide) |
20 | | - - [PHP Style Guide](#php-style-guide) |
21 | | - - [CSS/Styling Style Guide](#cssstyling-style-guide) |
22 | | -- [Pull Request Process](#pull-request-process) |
23 | | -- [Security Vulnerability Reporting](#security-vulnerability-reporting) |
| 11 | +- Keep architecture intact; no major redesign in maintenance changes. |
| 12 | +- Use smallest safe change that fully solves the issue. |
| 13 | +- Preserve multisite behavior and capability checks. |
| 14 | +- Never add unprefixed WordPress globals. |
| 15 | +- Sanitize → validate → escape for all external input paths. |
| 16 | +- Prepare every SQL query. |
24 | 17 |
|
25 | | -## Code of Conduct |
| 18 | +## Branching |
26 | 19 |
|
27 | | -This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md), [Ethics](ETHICS.md), and [Terms](TERMS.md). By participating, you are expected to uphold these policies c. Please report unacceptable behavior to the project lead. |
| 20 | +- Do not commit directly to `main`. |
| 21 | +- Use descriptive branches (`fix/...`, `docs/...`, `chore/...`). |
28 | 22 |
|
29 | | -## How Can I Contribute? |
| 23 | +## Required Checks Before PR |
30 | 24 |
|
31 | | -### Reporting Bugs |
| 25 | +Run: |
32 | 26 |
|
33 | | -Bugs are tracked as GitHub issues. Before opening a new issue, please perform a quick search to see if the problem has already been reported. |
34 | | - |
35 | | -When you are creating a bug report, please include as many details as possible: |
36 | | - |
37 | | -- **A clear and descriptive title** for the issue. |
38 | | -- **A detailed description of the problem.** |
39 | | -- **Steps to reproduce the behavior.** Be as specific as possible. |
40 | | -- **Expected behavior vs. actual behavior.** |
41 | | -- **Screenshots or screen recordings** are extremely helpful. |
42 | | -- **Environment details:** |
43 | | - - OS and version |
44 | | - - Browser and version |
45 | | - - Device type (if applicable) |
46 | | - - WordPress version |
47 | | - - Active plugins that might be relevant |
48 | | - |
49 | | -### Suggesting Enhancements |
50 | | - |
51 | | -Enhancement suggestions are tracked as GitHub issues. |
52 | | - |
53 | | -- **Use a clear and descriptive title.** |
54 | | -- **Provide a step-by-step description of the suggested enhancement** in as many details as possible. |
55 | | -- **Explain why this enhancement would be useful.** What problem does it solve? |
56 | | -- **Provide examples of how it would work.** Code snippets or mockups are welcome. |
57 | | - |
58 | | -### Your First Code Contribution |
59 | | - |
60 | | -Unsure where to begin? You can start by looking through `good-first-issue` and `help-wanted` issues. |
61 | | - |
62 | | -Before you start working on a feature or bug, **please communicate your intention** by commenting on the relevant issue or creating a new one. This prevents duplicated effort and allows for early architectural feedback. |
63 | | - |
64 | | -## Development Setup |
65 | | - |
66 | | -1. **Fork & Clone:** Fork the repository to your own GitHub account and clone it to your local machine. |
67 | | -2. **Branch:** Create a new feature branch from the `main` or `develop` branch. Branch names should be descriptive, using prefixes like `feature/`, `bugfix/`, or `refactor/`. |
68 | | - ```bash |
69 | | - git checkout -b feature/my-new-feature-name |
70 | | - ``` |
71 | | -3. **Install Dependencies:** This project uses `pnpm` as its package manager. |
72 | | - ```bash |
73 | | - pnpm install |
74 | | - ``` |
75 | | -4. **Build Assets:** Run the build command to compile JavaScript and CSS. |
76 | | - ```bash |
77 | | - pnpm build |
78 | | - ``` |
79 | | -5. **Linting:** Before committing, ensure your code adheres to our standards by running the linter. |
80 | | - ```bash |
81 | | - pnpm lint |
82 | | - ``` |
83 | | - To automatically fix issues, you can run: |
84 | | - ```bash |
85 | | - pnpm format |
86 | | - ``` |
87 | | - |
88 | | -## Style Guides |
89 | | - |
90 | | -### Git Commit Messages |
91 | | - |
92 | | -- Use the present tense ("Add feature" not "Added feature"). |
93 | | -- Use the imperative mood ("Move file to..." not "Moves file to..."). |
94 | | -- Limit the first line to 72 characters or less. |
95 | | -- Reference issues and pull requests liberally in the commit body. |
96 | | - |
97 | | -Example: |
98 | | - |
99 | | -``` |
100 | | -feat: Add chunked TUS upload strategy |
101 | | - |
102 | | -Implements the resilient, chunked TUS uploader in the Core module. |
103 | | -This allows for the upload of large files (>5MB) without crashing the |
104 | | -browser tab, which is critical for handling external music files. |
105 | | -The upload strategy now correctly falls back to this method based on |
106 | | -the file size and environment profile. |
107 | | - |
108 | | -Fixes #42 |
| 27 | +```bash |
| 28 | +composer run lint |
| 29 | +composer run analyze |
| 30 | +composer run test:unit |
| 31 | +pnpm run lint |
| 32 | +pnpm run build |
109 | 33 | ``` |
110 | 34 |
|
111 | | -### JavaScript Style Guide |
112 | | -
|
113 | | -All JavaScript must adhere to the configuration in our `.eslintrc.js` file. |
114 | | -- Use ES Modules (`import`/`export`) for all new JavaScript. |
115 | | -- Avoid global scope pollution. |
116 | | -- Write clear, self-documenting code. Add JSDoc comments for all public functions and complex logic. |
117 | | -
|
118 | | -### PHP Style Guide |
119 | | -
|
120 | | -All PHP code must adhere to the [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/). |
121 | | -- Use strict types (`declare(strict_types=1);`) where possible. |
122 | | -- Use namespaces for all classes. |
123 | | -
|
124 | | -### CSS/Styling Style Guide |
125 | | -
|
126 | | -- All CSS must adhere to the configuration in our `.stylelintrc.js` file. |
127 | | -- Use BEM (Block, Element, Modifier) naming conventions for CSS classes (e.g., `.starmus-recorder__button--primary`). |
128 | | -
|
129 | | -## Pull Request Process |
| 35 | +If a command fails due an existing repository baseline issue, call it out in the PR and confirm your change did not introduce new failures. |
130 | 36 |
|
131 | | -1. **Ensure all tests and linting checks pass** before submitting your PR. |
132 | | -2. **Update the `README.md` and any relevant documentation** with details of changes to the interface, new environment variables, etc. |
133 | | -3. **Create a Pull Request** against the `main` or `develop` branch of the main repository. |
134 | | -4. **Provide a clear title and description** for your PR, explaining the "why" and "what" of your changes. Link to the issue(s) your PR resolves. |
135 | | -5. **Request a Review:** Tag the project lead or relevant team members for review. |
136 | | -6. **Respond to Feedback:** The reviewer may ask for changes. Please be open to discussion and make the required updates. Once your PR is approved, it will be merged by a maintainer. |
| 37 | +## Pull Request Expectations |
137 | 38 |
|
138 | | -## Security Vulnerability Reporting |
| 39 | +Include in every PR: |
139 | 40 |
|
140 | | -If you discover a security vulnerability, please **DO NOT** open a public issue. Instead, send a private email to `security@sparxstar.com` (or your designated security contact). |
| 41 | +- summary of changes |
| 42 | +- rationale (why) |
| 43 | +- testing performed |
| 44 | +- security impact (if any) |
| 45 | +- docs updated (if behavior/public API changed) |
141 | 46 |
|
142 | | -We take security seriously and will respond promptly. |
| 47 | +## Security Reports |
143 | 48 |
|
| 49 | +Do not open public issues for vulnerabilities. Follow `SECURITY.md`. |
0 commit comments