]>
Commit | Line | Data |
---|---|---|
3821b1ee | 1 | ## Contributing to Shaarli (community repository) |
2 | ||
3 | ### Bugs and feature requests | |
4 | **Reporting bugs, feature requests: issues management** | |
5 | ||
6 | You can look through existing bugs/requests and help reporting them [here](https://github.com/shaarli/Shaarli/issues). | |
7 | ||
8 | Constructive input/experience reports/helping other users is welcome. | |
9 | ||
10 | The 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 | ||
12 | Check 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 | 21 | The [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 | 23 | To 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 | |
26 | Currently 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 | |
29 | You can help testing Shaarli releases by immediately upgrading your installation after a [new version has been releases](https://github.com/shaarli/Shaarli/releases). | |
30 | ||
31 | All 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 | |
34 | git clone https://github.com/shaarli/Shaarli | |
35 | git remote add pull-request-25 owner/cool-new-feature | |
36 | git remote add pull-request-26 anotherowner/bugfix | |
37 | git remote update | |
38 | git checkout -b testing | |
39 | git merge cool-new-feature | |
40 | git merge bugfix | |
41 | ``` | |
927a8411 | 42 | Or see [Checkout Github Pull Requests locally](https://gist.github.com/piscisaureus/3342247) |
3821b1ee | 43 | |
44 | Please 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 | ||
60 | All 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 | ||
64 | TODO | |
65 | ||
66 | #### Useful links | |
67 | If 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 |