]> git.immae.eu Git - github/shaarli/Shaarli.git/blame - CONTRIBUTING.md
wildcard tag search support
[github/shaarli/Shaarli.git] / CONTRIBUTING.md
CommitLineData
3821b1ee 1## Contributing to Shaarli (community repository)
2
3### Bugs and feature requests
4**Reporting bugs, feature requests: issues management**
5
6You can look through existing bugs/requests and help reporting them [here](https://github.com/shaarli/Shaarli/issues).
7
8Constructive input/experience reports/helping other users is welcome.
9
10The general guideline of the fork is to keep Shaarli simple (project and code maintenance, and features-wise), while providing customization capabilities (plugin system, making more settings configurable).
11
12Check the [milestones](https://github.com/shaarli/Shaarli/milestones) to see what issues have priority.
13
14 * The issues list should preferably contain **only tasks that can be actioned immediately**. Anyone should be able to open the issues list, pick one and start working on it immediately.
15 * If you have a clear idea of a **feature you expect, or have a specific bug/defect to report**, [search the issues list, both open and closed](https://github.com/shaarli/Shaarli/issues?q=is%3Aissue) to check if it has been discussed, and comment on the appropriate issue. If you can't find one, please open a [new issue](https://github.com/shaarli/Shaarli/issues/new)
16 * **General discussions** fit in #44 so that we don't follow a slope where users and contributors have to track 90 "maybe" items in the bug tracker. Separate issues about clear, separate steps can be opened after discussion.
17 * You can also join instant discussion at https://gitter.im/shaarli/Shaarli, or via IRC as described [here](https://github.com/shaarli/Shaarli/issues/44#issuecomment-77745105)
18
19### Documentation
3821b1ee 20
70cb8835 21The [official documentation](http://shaarli.readthedocs.io/en/rtfd/) is generated from [Markdown](https://daringfireball.net/projects/markdown/syntax) documents in the `doc/md/` directory. HTML documentation is generated using [Mkdocs](http://www.mkdocs.org/). [Read the Docs](https://readthedocs.org/) provides hosting for the online documentation.
3821b1ee 22
a6192bdd 23To edit the documentation, please edit the appropriate `doc/md/*.md` files (and optionally `make htmlpages` to preview changes to HTML files). Then submit your changes as a Pull Request. Have a look at the MkDocs documentation and configuration file `mkdocs.yml` if you need to add/remove/rename/reorder pages.
3821b1ee 24
25### Translations
26Currently Shaarli has no translation/internationalization/localization system available and is single-language. You can help by proposing an i18n system (issue https://github.com/shaarli/Shaarli/issues/121)
27
28### Beta testing
29You can help testing Shaarli releases by immediately upgrading your installation after a [new version has been releases](https://github.com/shaarli/Shaarli/releases).
30
31All current development happens in [Pull Requests](https://github.com/shaarli/Shaarli/pulls). You can test proposed patches by cloning the Shaarli repo, adding the Pull Request branch and `git checkout` to it. You can also merge multiple Pull Requests to a testing branch.
32
33```bash
34git clone https://github.com/shaarli/Shaarli
35git remote add pull-request-25 owner/cool-new-feature
36git remote add pull-request-26 anotherowner/bugfix
37git remote update
38git checkout -b testing
39git merge cool-new-feature
40git merge bugfix
41```
927a8411 42Or see [Checkout Github Pull Requests locally](https://gist.github.com/piscisaureus/3342247)
3821b1ee 43
44Please report any problem you might find.
45
46
47### Contributing code
48
49#### Adding your own changes
50
51 * Pick or open an issue
52 * Fork the Shaarli repository on github
53 * `git clone` your fork
54 * starting from branch ` master`, switch to a new branch (eg. `git checkout -b my-awesome-feature`)
55 * edit the required files (from the Github web interface or your text editor)
56 * add and commit your changes with a meaningful commit message (eg `Cool new feature, fixes issue #1001`)
cc8f572b 57 * run unit tests against your patched version, see [Running unit tests](https://shaarli.readthedocs.io/en/master/Unit-tests/#run-unit-tests)
3821b1ee 58 * Open your fork in the Github web interface and click the "Compare and Pull Request" button, enter required info and submit your Pull Request.
59
60All changes you will do on the `my-awesome-feature` in the future will be added to your Pull Request. Don't work directly on the master branch, don't do unrelated work on your `my-awesome-feature` branch.
61
62#### Contributing to an existing Pull Request
63
64TODO
65
66#### Useful links
67If you are not familiar with Git or Github, here are a few links to set you on track:
68
69 * https://try.github.io/ - 10 minutes Github workflow interactive tutorial
70 * http://ndpsoftware.com/git-cheatsheet.html - A Git cheatsheet
71 * http://www.wei-wang.com/ExplainGitWithD3 - Helps you understand some basic Git concepts visually
72 * https://www.atlassian.com/git/tutorial - Git tutorials
73 * https://www.atlassian.com/git/workflows - Git workflows
74 * http://git-scm.com/book - The official Git book, multiple languages
75 * http://www.vogella.com/tutorials/Git/article.html - Git tutorials
76 * http://think-like-a-git.net/resources.html - Guide to Git
77 * http://gitready.com/ - medium to advanced Git docs/tips/blog/articles
78 * https://github.com/btford/participating-in-open-source - Participating in Open Source