Add tips for new contributors; improve issue templates

This commit is contained in:
starkos 2020-10-24 12:31:38 -04:00
parent c6580ff1ce
commit 76359f4c53
5 changed files with 43 additions and 6 deletions

View File

@ -7,6 +7,8 @@ assignees: ''
---
_Before asking a new question, please [use the issue search feature](https://github.com/premake/premake-core/issues) to see if your question has already been asked. Help us help you!_
**What's your question?**
A short, concise question for the community. To get the best answers, be clear about what you're asking, what kind of responses you hope to receive, and how you intend to use the information.

View File

@ -7,6 +7,8 @@ assignees: ''
---
_Before opening a new issue, please [use the issue search feature](https://github.com/premake/premake-core/issues) to see if a similar issue already exists. If not, please help us help you by filling in the template below._
**What are you trying to do?**
A short, concise description of the outcome you are trying to achieve, ex. "Add build settings to a specific file".

View File

@ -7,6 +7,8 @@ assignees: ''
---
_Before opening a new bug report, please read [Reporting Bugs](https://github.com/premake/premake-core/blob/master/CONTRIBUTING.md#reporting-bugs) and consider if this is something [you can contribute](https://github.com/premake/premake-core/blob/master/CONTRIBUTING.md#contributing-a-fix-or-feature) yourself. If this a new bug, help us help you by filling in the template below._
**What seems to be the problem?**
A clear and concise description of the bug, ex. "It crashes when I try to run it" or "There doesn't seem to be any way to do ...". If you are reporting a crash, be sure to include any error messages and stack trace information. Use [code blocks](https://help.github.com/en/articles/creating-and-highlighting-code-blocks) to format code and console output nicely.

View File

@ -7,6 +7,8 @@ assignees: ''
---
_Before opening a new feature request, please read [Requesting New Features](https://github.com/premake/premake-core/blob/master/CONTRIBUTING.md#requesting-new-features) and consider if this is something [you can contribute](https://github.com/premake/premake-core/blob/master/CONTRIBUTING.md#contributing-a-fix-or-feature) yourself. If this a new request, help us help you by filling in the template below._
**What problem will this solve?**
A clear and concise description of the problem this new feature is meant to solve, ex. "I'm always frustrated when [...]" or "Add support for this new toolset [...]". Please limit your request to a single feature; create multiple feature requests instead.

View File

@ -4,17 +4,25 @@ Thanks for your interest in contributing to Premake! :tada: We love getting [pul
We want to keep it as easy as possible to contribute changes. These guidelines are intended to help smooth that process, and allow us to review and approve your changes quickly and easily. Improvements are always welcome! Feel free to [open an issue][issue-tracker] or [submit a new pull request][submit-pr]. And finally, these are just guidelines, not rules, so use your best judgement when necessary.
We do everything in [Git][git] hosted on [GitHub][github]. If you're new to this environment, you may want to begin with [Getting Started with GitHub](https://help.github.com/en/categories/getting-started-with-github) and the Thinkful's [GitHub Pull Request Tutorial](https://www.thinkful.com/learn/github-pull-request-tutorial/).
We do everything in [Git][git] hosted on [GitHub][github]. If you're new to this environment, you may want to begin with [Getting Started with GitHub](gh-start) and [Thinkful's GitHub Pull Request Tutorial](thinkful).
## Reporting Bugs
Bugs should be reported on our [GitHub Issue Tracker][issue-tracker].
Follow the advice in [How do I ask a good question?][how-to-ask]. While the article is intended for people asking questions on [StackOverflow](https://stackoverflow.com/), it all applies to writing a good bug report too.
Please consider if this is something [you can contribute](#contributing-a-fix-or-feature) yourself. Premake is a community project run by volunteers; the best way to get something fixed is to become a contributor!
Before opening an issue, use the search feature at the top of that page to see if it has already been reported.
If you've discovered a new bug, please follow the advice in [How do I ask a good question?][how-to-ask]. While the article is intended for people asking questions on [StackOverflow](https://stackoverflow.com/), it all applies to writing a good bug report too.
## Requesting New Features
Feature requests should also be sent to our [GitHub Issue Tracker][issue-tracker].
Feature requests should be sent to our [GitHub Issue Tracker][issue-tracker].
Please consider if this is something [you can contribute](#contributing-a-fix-or-feature) yourself. Premake is a community project run by volunteers; the best way to get a feature built is to become a contributor!
Before opening a new request, use the search feature at the top of that page to see if it has already been requested.
- Explain the problem that you're having, and anything you've tried to solve it using the currently available features
@ -32,11 +40,30 @@ You've created a new fix or feature for Premake. Awesome!
2. Create a topic branch, and make all of your changes on that branch
3. Submit a pull request
3. Submit a pull request; see [Writing a Good Pull Request](#writing-a-good-pull-request)
4. Give us a moment. Premake is maintained by only a few people, all of whom are doing this on their limited free time, so it may take us a bit to review your request. We're working on improving our turnaround time with resources like this guide and [our OpenCollective][collective].
4. Give us a moment. Premake is maintained volunteers on their free time, so we might not be able to respond right away. We're working on improving our turnaround time with resources like this guide and [our OpenCollective][collective].
If you're not sure what any of that means, check out [Getting Started with GitHub](gh-start) and [Thinkful's GitHub Pull Request Tutorial](thinkful) for a complete walkthrough of the process. Gain a life skill!
Some tips...
- Don't hesitate to ask questions on the [issue tracker](issue-tracker) if you get stuck. We're always happy to help people who are trying to contribute. Help us help you help us!
- See [BUILD.txt](https://github.com/premake/premake-core/blob/master/BUILD.txt) for help getting your first build of Premake working. Be sure to run the unit tests!
- Understand exactly what needs to change in Premake's output to get the effect you want. Start by manually creating a working project script to use as a reference, either by adjusting Visual Studio project settings and inspecting the results, or by hand-editing Premake generated project files. Know exactly what you need Premake to do differently before diving in.
- Search the Premake code to find the element you want to change, or those nearby. This should turn up the right location to cut in your change, and also highlight the unit tests that cover that part of the code.
- Copy and paste one of the existing unit tests, and then modify it to match the output you're trying to achieve. If you run the tests again you should see your new test (and only your new test) fail.
- If you need to add new configuration switch(es) to support your feature, you can do that using `api.register()` in [_premake_init.lua](https://github.com/premake/premake-core/blob/master/src/_premake_init.lua).
- [Overrides and Call Arrays](https://github.com/premake/premake-core/wiki/Overrides-and-Call-Arrays) explains how and why we're organizing the code the way we are. Bonus points for converting older code (i.e. GMake and Xcode exporters) to this new and improved format.
- Once everything is working the way you like it, you're ready to submit a pull request for us to merge!
If you're not sure what any of that means, check out Thinkful's [GitHub Pull Request Tutorial](https://www.thinkful.com/learn/github-pull-request-tutorial/) for a complete walkthrough of the process.
### Writing a Good Pull Request
@ -62,8 +89,10 @@ If you're not sure what any of that means, check out Thinkful's [GitHub Pull Req
[collective]: https://opencollective.com/premake
[gh-start]: https://help.github.com/en/categories/getting-started-with-github
[git]: https://git-scm.com
[github]: https://github.com
[how-to-ask]: https://stackoverflow.com/help/how-to-ask
[issue-tracker]: https://github.com/premake/premake-core/issues
[submit-pr]: https://github.com/premake/premake-core/pulls
[thinkful]: https://www.thinkful.com/learn/github-pull-request-tutorial/