|
| 1 | +# Contributing to Imagination Media XML Validator |
| 2 | + |
| 3 | +First off, thanks for taking the time to contribute! ❤️ |
| 4 | + |
| 5 | +All types of contributions are encouraged and valued. See the |
| 6 | +[Table of Contents] for different ways to help and details about how this |
| 7 | +project handles them. Please make sure to read the relevant section before |
| 8 | +making your contribution. It will make it a lot easier for our developers and |
| 9 | +smooth out the experience for all involved. We look forward to your |
| 10 | +contributions! |
| 11 | + |
| 12 | +If you like the project, but just don't have time to contribute, that's fine. |
| 13 | +Here are other easy ways to support the project and show your appreciation, |
| 14 | +which we would also be very happy about: |
| 15 | +- Star the project |
| 16 | +- Tweet about it |
| 17 | +- Mention the project at local meetups and tell your friends/colleagues |
| 18 | + |
| 19 | +## Table of Contents |
| 20 | + |
| 21 | +- [I Have a Question](#i-have-a-question) |
| 22 | +- [I Want to Contribute](#i-want-to-contribute) |
| 23 | +- [Reporting Bugs](#reporting-bugs) |
| 24 | +- [Suggesting Enhancements](#suggesting-enhancements) |
| 25 | +- [Style Guides](#style-guides) |
| 26 | + - [Commit Messages](#commit-messages) |
| 27 | +- [Join The Team](#join-the-team) |
| 28 | + |
| 29 | +## I Have a Question |
| 30 | + |
| 31 | +If you want to ask a question, we assume that you have read the [documentation]. |
| 32 | + |
| 33 | +Before you ask a question, it is best to search for existing [issues] that might |
| 34 | +help you. If you have found a suitable issue and still need clarification, you |
| 35 | +can ask your question in that issue. It is also advisable to search the Internet |
| 36 | +for answers first. |
| 37 | + |
| 38 | +If you then still feel the need to ask a question and need clarification, we |
| 39 | +recommend the following: |
| 40 | + |
| 41 | +- Open a [new issue] |
| 42 | +- Provide as much context as you can about the problem that you're running into. |
| 43 | +(What you were doing when it occurred, what you expected to happen, steps to |
| 44 | +reproduce the issue, etc.) |
| 45 | +- Provide your Magento Open Source or Adobe Commerce and PHP versions |
| 46 | +- Provide a list of any additional third-party extensions installed that might |
| 47 | +cause a conflict |
| 48 | + |
| 49 | +We will then take care of the issue as soon as possible. |
| 50 | + |
| 51 | +## I Want to Contribute |
| 52 | + |
| 53 | +### Legal Notice |
| 54 | + |
| 55 | +When contributing to this project, you must agree that you have authored 100% of |
| 56 | +the content, that you have the necessary rights to the content and that the |
| 57 | +content you contribute may be provided under the project [license]. |
| 58 | + |
| 59 | +### Reporting Bugs |
| 60 | + |
| 61 | +#### Before Submitting a Bug Report |
| 62 | + |
| 63 | +A good bug report shouldn't leave others needing to chase you down for more |
| 64 | +information. Therefore, we ask you to investigate carefully, collect information |
| 65 | +and describe the issue in detail in your report. Please complete the following |
| 66 | +steps in advance to help us fix any potential bug as fast as possible. |
| 67 | + |
| 68 | +- Make sure that you are using the latest version |
| 69 | +- Determine if your bug is really a bug and not an error on your side (e.g. |
| 70 | +using incompatible environment components/versions). Make sure that you have |
| 71 | +read the [documentation]. If you are looking for support, please see the |
| 72 | +"[I Have a Question]" section. |
| 73 | +- To see if other users have experienced (and potentially already solved) the |
| 74 | +same issue you are having, check if there is not already a bug report existing |
| 75 | +for your bug or error in the [bug tracker] |
| 76 | +- Please also make sure to search the Internet (including Stack Overflow) to see |
| 77 | +if users outside of the GitHub community have discussed the issue |
| 78 | +- Collect information about the bug: |
| 79 | + - Stack trace (if available) |
| 80 | + - OS and Version (e.g. Windows 11, Ubuntu Linux 04.22, macOS Ventura 13.0.1) |
| 81 | + - Versions of Magento Open Source or Adobe Commerce and PHP |
| 82 | + - Your input and the output of the tool |
| 83 | + - Whether you can reliably reproduce the issue and if can you also reproduce |
| 84 | + it with older versions of the tool |
| 85 | + |
| 86 | +#### How Do I Submit a Good Bug Report? |
| 87 | + |
| 88 | +You must never report security related issues, vulnerabilities or bugs including |
| 89 | +sensitive information to the issue tracker, or elsewhere in public. Instead, |
| 90 | +sensitive bugs must be sent by email to [support@imaginationmedia.com]. |
| 91 | + |
| 92 | +We use GitHub issues to track bugs and errors. If you run into an issue with the |
| 93 | +project: |
| 94 | + |
| 95 | +- Open a [new issue]. (Since we can't be sure at this point whether it is a bug |
| 96 | +or not, we ask you not to talk about a bug yet and not to label the issue.) |
| 97 | +- Explain the behavior you would expect and the actual behavior |
| 98 | +- Please provide as much context as possible and describe the |
| 99 | +*reproduction steps* that someone else can follow to recreate the issue on their |
| 100 | +own. For good bug reports, you should isolate the problem and create a reduced |
| 101 | +test case. |
| 102 | +- Provide the information you collected in the previous section |
| 103 | + |
| 104 | +Once it's filed: |
| 105 | + |
| 106 | +- The development team will label the issue accordingly |
| 107 | +- A team member will try to reproduce the issue with your provided steps. If |
| 108 | +there are no reproduction steps or no obvious way to reproduce the issue, the |
| 109 | +team will ask you for those steps and mark the issue as `needs-reproduction`. |
| 110 | +Bugs with the `needs-reproduction` tag will not be addressed until they are |
| 111 | +reproduced. |
| 112 | +- If our team is able to reproduce the issue, it will be marked `needs-fix`, as |
| 113 | +well as possibly other tags (such as `critical`) and the issue will be assigned |
| 114 | +to be implemented by a developer. |
| 115 | + |
| 116 | +### Suggesting Enhancements |
| 117 | + |
| 118 | +This section guides you through submitting an enhancement suggestion for |
| 119 | +Imagination Media XML Validator, **including completely new features and minor |
| 120 | +improvements to existing functionality**. Following these guidelines will help |
| 121 | +our developers and the community to understand your suggestion and find related |
| 122 | +suggestions. |
| 123 | + |
| 124 | +#### Before Submitting an Enhancement |
| 125 | + |
| 126 | +- Make sure that you are using the latest version |
| 127 | +- Read the [documentation] carefully and find out if the functionality is |
| 128 | +already covered |
| 129 | +- Search the existing [issues] to see if the enhancement has already been |
| 130 | +suggested. If it has, add a comment to the existing issue instead of opening a |
| 131 | +new one. |
| 132 | +- Determine whether your idea fits with the scope and aims of the project. |
| 133 | +It is up to you to make a strong case to convince the project's developers of |
| 134 | +the merits of this feature. Please keep in mind that we want features that will |
| 135 | +be useful to the majority of our users and not just a small subset. If you're |
| 136 | +only targeting a minority of users, please consider writing an add-on extension. |
| 137 | + |
| 138 | +#### How Do I Submit a Good Enhancement Suggestion? |
| 139 | + |
| 140 | +Enhancement suggestions are tracked as [GitHub issues]. |
| 141 | + |
| 142 | +- Use a **clear and descriptive title** for the issue to identify the |
| 143 | +suggestion. |
| 144 | +- Provide a **step-by-step description of the suggested enhancement** in as many |
| 145 | +details as possible. |
| 146 | +- **Describe the current behavior** and **explain which behavior you expected to |
| 147 | +see instead** and why. At this point, you can also tell us which alternatives do |
| 148 | +not work for you. |
| 149 | +- You may want to **include screenshots and animated GIFs** which help you |
| 150 | +demonstrate the steps or point out the part which the suggestion is related to. |
| 151 | +You can use [LICEcap] to record GIFs on macOS and Windows and [Silentcast] on |
| 152 | +Linux. Alternatively, [Loom] is a paid screen recording app available for macOS, |
| 153 | +Windows and other platforms. |
| 154 | +- **Explain why this enhancement would be useful** to most users. You may also |
| 155 | +want to point out the other projects that solved it better and which could serve |
| 156 | +as inspiration. |
| 157 | + |
| 158 | +## Style Guides |
| 159 | +### Commit Messages |
| 160 | +Please use clear and concise messages in the imperative form that are between 50 |
| 161 | +and 55 characters in length. Additional details may be included in subsequent |
| 162 | +description lines (proceeded by a blank line for the first line) if needed. |
| 163 | +Please see [How to Write a Commit Message by Chris Beams] for more specific |
| 164 | +guidelines. |
| 165 | + |
| 166 | +## Join the Team |
| 167 | + |
| 168 | +Want to get paid to work on exciting Magento Open Source and Adobe Commerce |
| 169 | +projects like this? [Join the Imagination Media team]! |
| 170 | + |
| 171 | +## Attribution |
| 172 | + |
| 173 | +This guide is based on the example generated by the [contributing.md generator]. |
| 174 | + |
| 175 | +[Table of Contents]: #table-of-contents |
| 176 | +[documentation]: README.md |
| 177 | +[issues]: https://github.com/Imagination-Media/magento-module-xml-validator/issues |
| 178 | +[new issue]: https://github.com/Imagination-Media/magento-module-xml-validator/issues/new |
| 179 | +[license]: ./LICENSE |
| 180 | +[I Have a Question]: #i-have-a-question |
| 181 | +[bug tracker]: https://github.com/Imagination-Media/magento-module-xml-validator/issues?q=label%3Abug |
| 182 | +[support@imaginationmedia.com]: mailto:support@imaginationmedia.com?subject=Security%20Issue%20in%20XML%20Validator |
| 183 | +[GitHub issues]: https://github.com/Imagination-Media/magento-module-xml-validator/issues |
| 184 | +[LICEcap]: https://www.cockos.com/licecap/ |
| 185 | +[Silentcast]: https://github.com/colinkeenan/silentcast |
| 186 | +[Loom]: https://www.loom.com/ |
| 187 | +[How to Write a Commit Message by Chris Beams]: https://cbea.ms/git-commit/ |
| 188 | +[Join the Imagination Media team]: https://imaginationmedia.com/careers |
| 189 | +[contributing.md generator]: https://generator.contributing.md/ |
0 commit comments