|
| 1 | + |
| 2 | + |
| 3 | +First off, thank you for considering contributing to Dashy! There are two main ways you can help out: [Submitting a Pull Request](#submitting-a-pr) or [Raising an Issue](#raising-an-issue). |
| 4 | + |
| 5 | +### Submitting a PR |
| 6 | + |
| 7 | +Pull requests are proposed code changes, that can then be directly merged into Dashy's master branch and deployed to users. Even a small PR would be a big help. |
| 8 | + |
| 9 | +Not sure what to work on? Here are some ideas: |
| 10 | +- Fix a bug, or solve an open issue |
| 11 | +- Improve the docs |
| 12 | +- Add a new theme |
| 13 | +- Implement a new widget |
| 14 | +- Add more display options |
| 15 | +- Refactor or improve an area of the code |
| 16 | +- Implement a new feature, or improve an existing one |
| 17 | + |
| 18 | +Before you submit your pull request, please ensure the following: |
| 19 | +- Must be backwards compatible |
| 20 | +- All lint checks and tests must pass |
| 21 | +- If a new option in the the config file is added, it needs to be added into the schema, and documented in the configuring guide |
| 22 | +- If a new dependency is required, it must be essential, and it must be thoroughly checked out for security or efficiency issues |
| 23 | + |
| 24 | +Please also include the following information in your PR: |
| 25 | +- PR type (bug fix, feature, code style updates, documentation, etc) |
| 26 | +- Issue number (if applicable) |
| 27 | +- A brief description of your changes |
| 28 | +- A note confirming that your code follows the checklist (above) |
| 29 | + |
| 30 | +#### Getting Started |
| 31 | + |
| 32 | +To set up your development environment, and get Dashy running locally, please see: [Developing Docs](/docs/developing.md) |
| 33 | + |
| 34 | +#### For new Contributors |
| 35 | + |
| 36 | +If you have never created a pull request before, welcome :tada: :smile: [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) |
| 37 | +on how to create a pull request.. |
| 38 | + |
| 39 | +1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, |
| 40 | + and configure the remotes: |
| 41 | + |
| 42 | + ```bash |
| 43 | + # Clone your fork of the repo into the current directory |
| 44 | + git clone https://github.com/<your-username>/<repo-name> |
| 45 | + # Navigate to the newly cloned directory |
| 46 | + cd <repo-name> |
| 47 | + # Assign the original repo to a remote called "upstream" |
| 48 | + git remote add upstream https://github.com/hoodiehq/<repo-name> |
| 49 | + ``` |
| 50 | + |
| 51 | +2. If you cloned a while ago, get the latest changes from upstream: |
| 52 | + |
| 53 | + ```bash |
| 54 | + git checkout master |
| 55 | + git pull upstream master |
| 56 | + ``` |
| 57 | + |
| 58 | +3. Create a new topic branch (off the main project development branch) to |
| 59 | + contain your feature, change, or fix: |
| 60 | + |
| 61 | + ```bash |
| 62 | + git checkout -b <topic-branch-name> |
| 63 | + ``` |
| 64 | + |
| 65 | +4. Make sure to update, or add to the tests when appropriate. Patches and |
| 66 | + features will not be accepted without tests. Run `yarn test` to check that |
| 67 | + all tests pass after you've made changes. |
| 68 | + |
| 69 | +5. If you added or changed a feature, make sure to document it accordingly in |
| 70 | + the docs and if applicable, in the `README.md` file. |
| 71 | + |
| 72 | +6. Push your topic branch up to your fork: |
| 73 | + |
| 74 | + ```bash |
| 75 | + git push origin <topic-branch-name> |
| 76 | + ``` |
| 77 | + |
| 78 | +8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) |
| 79 | + with a clear title and description. |
| 80 | + |
| 81 | +#### Testing the Production App |
| 82 | + |
| 83 | +For larger pull requests, please also check that it works as expected in a production environment. |
| 84 | + |
| 85 | +Testing production app in development environment: |
| 86 | +- Natively |
| 87 | + - Build: `yarn build` |
| 88 | + - Run: `yarn start` |
| 89 | +- With Docker: |
| 90 | + - Build: `docker build -t dashy .` |
| 91 | + - Run: `docker run -p 8080:80 dashy` |
| 92 | + |
| 93 | +Please also ensure that running the following scripts return no errors: |
| 94 | +- `yarn lint` |
| 95 | +- `yarn test` |
| 96 | +- `yarn validate-config` |
| 97 | + |
| 98 | +A good resource for testing the Docker image on a totally fresh system, is by using [Play with Docker](https://labs.play-with-docker.com/). This will let you clone or pull your image, and spin up a container. This is useful for checking that everything behaves as it should on an independent system, and should get around the _'works on my computer'_ issue. |
| 99 | + |
| 100 | +#### Merging a PR |
| 101 | + |
| 102 | +Only maintainers can merge a PR. A pull request can only be merged if: |
| 103 | +- All CI checks are passing |
| 104 | +- It has been approved by either the author, or at least two maintainers |
| 105 | +- It has no requested changes |
| 106 | +- It is up to date with current master |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +### Raising an Issue |
| 111 | + |
| 112 | +If you've found a bug, or something that isn't working as you'd expect, please raise an issue, so that it can be resolved. If you're having trouble getting things up and running, feel free to ask a question. Feature requests and feedback are also welcome, as it helps Dashy improve. |
| 113 | + |
| 114 | +Click one of the links below, to open an issue: |
| 115 | +- [Raise a Bug 🐛](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D) - Found a bug, or something not working as it should? |
| 116 | +- [Submit a Feature Request 🦄](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A6%84+Feature+Request&template=feature-request---.md&title=%5BFEATURE_REQUEST%5D) - Is there a feature that you think is missing from Dashy? |
| 117 | +- [Ask a Question 🤷♀️](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question------.md&title=%5BQUESTION%5D) - Got a question about using, building or developing Dashy? |
| 118 | +- [Share Feedback 🌈](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%8C%88+Feedback&template=share-feedback---.md&title=%5BFEEDBACK%5D) - Got any thoughts on the current or future development of Dashy? |
| 119 | + |
| 120 | +--- |
| 121 | + |
| 122 | +### Contributors |
| 123 | + |
| 124 | + |
| 125 | + |
| 126 | +### Star-Gazers Over Time |
| 127 | + |
| 128 | + |
| 129 | + |
0 commit comments