kamilion/customizer

Add contributing guidelines

Closed this issue · 1 comments

This is part of issue #129 that aims to provide contributing guidelines, which is recommended by GitHub. By following the recommendation, the content will be more accessible than now.

Justification

Our Wiki has created "Contribute" page back in April 2015. I wasn't aware and unsure if the recommendation by GitHub had been online during that time. Despite this, the page isn't noticeable unless one visits the Wiki and access to the page from the sidebar menu.

By following the setting guidelines, its content will be more accessible than before:

To help your project contributors do good work, you can add a file with contribution guidelines to the root of your project's repository. Then, whenever someone opens a pull request or creates an issue, they will see a link to that file.

Adding guideline

There are two ways to add the guideline: create a new file in the repository's root directory, or in a hidden directory .github/. For time being, there isn't any need to use the hidden directory to contain the only file. Therefore, CONTRIBUTING file shall be created in the repository's root directory.

Next, the new file is added to master branch either by direct commit or via pull request.

Pull request may be preferred so that additional commits can be made for cleaning up the content of guideline. For example, we no longer need the 'table of contents' formatting since the guideline will be moved away from Wiki and text shall be reduced for less reading.

Otherwise, direct commit will do the job fine if the guideline is already revised beforehand.

File formatting

For contributing guideline, I'd suggest to use all UPPERCASE letters to indicate standard file and added with markdown file extension. The resulting file name CONTRIBUTING.md shall be used.

The file extension will allow links and optional markdown formatting to be visible by default. Similar to README.md, the raw text shall include newlines for each line of text that has 70-characters width for ease of viewing in raw text form.

Note that 70-characters width limit is adopted by few projects that I had observed i.e. Tiny Core Linux README documentation. Many projects are being careless or rely too much on Markdown formatting that hides the poorly organized raw text by default.

Following above, the limit shall be applied as well to other files i.e. README.md and CHANGELOG to be consistent. Except, debian/copyright has limit of 60-characters width because the content requires to fit within optimal UI window size.

Reviewing guideline

When the guideline is created in the repository, the following shall apply:

  • "Contribute" page would be deprecated similar to "Changes log" and "Credits" pages; Means one less page to maintain on Wiki

  • for replacing initial notes made in commit ae89861, use text from existing 'Credits' tab, which reminds if there is any missing contributor in credits:

    If you know of anyone missing from this list, create a new issue and inform at
     https://github.com/clearkimura/Customizer/issues/new.
    Thanks to all who helped making this project useful to this date!
    
  • since contributing guideline is created in the repository, this also means relative link is effective and shall be used in CONTRIBUTING.md file

This issue should have been addressed earlier, but somehow overlooked until now.

The guideline is independent of other issues, therefore may be added before fixing inconsistent text and versioning. This shall be finished in patch release 4.1.4.

Added contributing guidelines in master branch.

P.S.: Removed entire content of "Contribute" and "Issue submission" pages on wiki, in favour of contributing guidelines. Sidebar menu on wiki also updated accordingly.