[github/shaarli/Shaarli.git] / CONTRIBUTING.md

## Contributing to Shaarli (community repository)

### Bugs and feature requests
**Reporting bugs, feature requests: issues management**

You can look through existing bugs/requests and help reporting them [here](https://github.com/shaarli/Shaarli/issues).

Constructive input/experience reports/helping other users is welcome.

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).

Check the [milestones](https://github.com/shaarli/Shaarli/milestones) to see what issues have priority.

 * 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.
 * 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)
 * **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.
 * 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)
 
### Documentation
**the [wiki](https://github.com/shaarli/Shaarli/wiki) is world-writable** - anyone can edit or add chapters and pages.

 * Large changes should preferably be discussed in [General discussion](https://github.com/shaarli/Shaarli/issues/44) beforehand (you can post a draft there and edit it).
 * If you create a new page, please link it from the new page (eg from the [Other links](https://github.com/shaarli/Shaarli/wiki#other-links) section.
 * The wiki is a general documentation about Shaarli:  usage, development, hacks, usage tricks, related links, projects. Try to keep it organized.
 * The wiki will be synced to Shaarli's `doc/` directory on each release. Keep that in mind when reviewing the quality of your edits.

You can make the project known by publishing blog posts/articles/videos about it and adding them to the links section in the wiki.

### Translations
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)

### Beta testing
You can help testing Shaarli releases by immediately upgrading your installation after a [new version has been releases](https://github.com/shaarli/Shaarli/releases).

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.

```bash
git clone https://github.com/shaarli/Shaarli
git remote add pull-request-25 owner/cool-new-feature
git remote add pull-request-26 anotherowner/bugfix
git remote update
git checkout -b testing
git merge cool-new-feature
git merge bugfix
```
Or see [Checkout Github Pull Requests locally](https://gist.github.com/piscisaureus/3342247)

Please report any problem you might find.


### Contributing code

#### Adding your own changes

 * Pick or open an issue
 * Fork the Shaarli repository on github
 * `git clone`  your fork
 * starting from branch ` master`, switch to a new branch (eg. `git checkout -b my-awesome-feature`)
 * edit the required files (from the Github web interface or your text editor)
 * add and commit your changes with a meaningful commit message (eg `Cool new feature, fixes issue #1001`)
 * run unit tests against your patched version, see [Running unit tests](https://github.com/shaarli/Shaarli/wiki/Running-unit-tests)
 * Open your fork in the Github web interface and click the "Compare and Pull Request" button, enter required info and submit your Pull Request.

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.

#### Contributing to an existing Pull Request

TODO

#### Useful links
If you are not familiar with Git or Github, here are a few links to set you on track:

 * https://try.github.io/ - 10 minutes Github workflow interactive tutorial
 * http://ndpsoftware.com/git-cheatsheet.html - A Git cheatsheet
 * http://www.wei-wang.com/ExplainGitWithD3 - Helps you understand some basic Git concepts visually
 * https://www.atlassian.com/git/tutorial - Git tutorials
 * https://www.atlassian.com/git/workflows - Git workflows
 * http://git-scm.com/book - The official Git book, multiple languages
 * http://www.vogella.com/tutorials/Git/article.html - Git tutorials
 * http://think-like-a-git.net/resources.html - Guide to Git
 * http://gitready.com/ - medium to advanced Git docs/tips/blog/articles
 * https://github.com/btford/participating-in-open-source - Participating in Open Source
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
	20	the [wiki](https://github.com/shaarli/Shaarli/wiki) is world-writable - anyone can edit or add chapters and pages.
	21
	22	* Large changes should preferably be discussed in [General discussion](https://github.com/shaarli/Shaarli/issues/44) beforehand (you can post a draft there and edit it).
	23	* If you create a new page, please link it from the new page (eg from the [Other links](https://github.com/shaarli/Shaarli/wiki#other-links) section.
	24	* The wiki is a general documentation about Shaarli: usage, development, hacks, usage tricks, related links, projects. Try to keep it organized.
	25	* The wiki will be synced to Shaarli's `doc/` directory on each release. Keep that in mind when reviewing the quality of your edits.
	26
	27	You can make the project known by publishing blog posts/articles/videos about it and adding them to the links section in the wiki.
	28
	29	### Translations
	30	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)
	31
	32	### Beta testing
	33	You can help testing Shaarli releases by immediately upgrading your installation after a [new version has been releases](https://github.com/shaarli/Shaarli/releases).
	34
	35	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.
	36
	37	```bash
	38	git clone https://github.com/shaarli/Shaarli
	39	git remote add pull-request-25 owner/cool-new-feature
	40	git remote add pull-request-26 anotherowner/bugfix
	41	git remote update
	42	git checkout -b testing
	43	git merge cool-new-feature
	44	git merge bugfix
	45	```
927a8411	46	Or see [Checkout Github Pull Requests locally](https://gist.github.com/piscisaureus/3342247)
3821b1ee	47
	48	Please report any problem you might find.
	49
	50
	51	### Contributing code
	52
	53	#### Adding your own changes
	54
	55	* Pick or open an issue
	56	* Fork the Shaarli repository on github
	57	* `git clone` your fork
	58	* starting from branch ` master`, switch to a new branch (eg. `git checkout -b my-awesome-feature`)
	59	* edit the required files (from the Github web interface or your text editor)
	60	* add and commit your changes with a meaningful commit message (eg `Cool new feature, fixes issue #1001`)
b6a88fab	61	* run unit tests against your patched version, see [Running unit tests](https://github.com/shaarli/Shaarli/wiki/Running-unit-tests)
3821b1ee	62	* Open your fork in the Github web interface and click the "Compare and Pull Request" button, enter required info and submit your Pull Request.
	63
	64	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.
	65
	66	#### Contributing to an existing Pull Request
	67
	68	TODO
	69
	70	#### Useful links
	71	If you are not familiar with Git or Github, here are a few links to set you on track:
	72
	73	* https://try.github.io/ - 10 minutes Github workflow interactive tutorial
	74	* http://ndpsoftware.com/git-cheatsheet.html - A Git cheatsheet
	75	* http://www.wei-wang.com/ExplainGitWithD3 - Helps you understand some basic Git concepts visually
	76	* https://www.atlassian.com/git/tutorial - Git tutorials
	77	* https://www.atlassian.com/git/workflows - Git workflows
	78	* http://git-scm.com/book - The official Git book, multiple languages
	79	* http://www.vogella.com/tutorials/Git/article.html - Git tutorials
	80	* http://think-like-a-git.net/resources.html - Guide to Git
	81	* http://gitready.com/ - medium to advanced Git docs/tips/blog/articles
	82	* https://github.com/btford/participating-in-open-source - Participating in Open Source