Skip to content

Commit 96127c5

Browse files
committed
Add minimal Readme and contributing docs
1 parent 19c8ff8 commit 96127c5

File tree

2 files changed

+54
-0
lines changed

2 files changed

+54
-0
lines changed

.github/CONTRIBUTING.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
Hi, thank you for your interest in contributing to the PHPCompatibility website! We look forward to working with you.
2+
3+
Aside from a few specific pages, the documentation on the website is automatically generated from the source code of the [PHPCompatibility repository](https://github.com/PHPCompatibility/PHPCompatibility).
4+
5+
The contents maintained in this repository are:
6+
- The pages in the "Using PHPCompatibility" section.
7+
- Site layout and structure.
8+
- CSS customizations.
9+
10+
Pull requests to improve either of these are welcome.
11+
12+
All the sniff and error code related content is auto-generated from a combination of:
13+
- The sniff class docblocks for each sniff in the [PHPCompatibility repo](https://github.com/PHPCompatibility/PHPCompatibility/PHPCompatibility/Sniffs)
14+
- The sniff specific additional documentation (if available) in the [PHPCompatibility repo](https://github.com/PHPCompatibility/PHPCompatibility/PHPCompatibility/Docs)
15+
16+
Improvements to the sniff and error code related content are very welcome, but should be pulled to the [PHPCompatibility repository](https://github.com/PHPCompatibility/PHPCompatibility).
17+
18+
19+
## How the website is generated
20+
21+
This website is a [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages) site using the [Jekyll Site Generator](https://jekyllrb.com/) with the [Liquid template language](https://shopify.github.io/liquid/) with some [Jekyll specific additions to Liquid](https://jekyllrb.com/docs/liquid/).
22+
23+
The website uses the [jekyll-rtd-theme](https://jekyll-rtd-theme.rundocs.io/) using the [rundocs core](https://rundocs.io/) with some site-specific customizations.
24+
25+
The website is automatically updated whenever a commit is pushed to this repository.
26+
27+
[TODO] Whenever a new release of the PHPCompatibility package is tagged, the documentation which is based on the source code of PHPCompatibility is automatically re-generated using the [PHPCS-docs](https://github.com/PHPCSStandards/phpcs-docs) generator package and committed to this repository via a GitHub actions workflow.
28+
29+
30+
## Testing the website locally
31+
32+
* Install a full [Ruby development environment](https://jekyllrb.com/docs/installation/)
33+
* Clone this repository
34+
* Go to the root directory of the clone of this repository
35+
* Run `bundle update`
36+
* Run `bundle exec jekyll serve`
37+
* You should now be able to open the website in your preferred browser at: http://localhost:4000/
38+
39+
For more information, see the [documentation on testing a GitHub Pages site locally](https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll).
40+
41+
42+
### Typical issues you may run into when testing the site locally
43+
44+
#### The GitHub API credentials you provided aren't valid.
45+
46+
Follow [these instructions](https://github.com/jekyll/github-metadata/blob/master/docs/authentication.md) on getting an access token set up.
47+
48+
49+

README.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
PHPCompatibility
2+
----
3+
4+
The source of the phpcompatibility.com website.
5+

0 commit comments

Comments
 (0)