Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update CONTRIBUTING.md #923

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update CONTRIBUTING.md #923

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 38 additions & 47 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# `Aima-Exercises`
# Aima-Exercises

Exercises for the book [*Artificial Intelligence: A Modern Approach.*](http://aima.cs.berkeley.edu/) The idea is that in the fourth edition of the book, exercises will be online only (they will not appear in the book). This site will showcase the exercises, and will be a platform for students and teachers to submit answers and have discussions about the exercises.

The present version of AIMA-Exercises uses Jekyll 3 and ruby 2.5.
The present version of AIMA-Exercises uses Jekyll 3 and Ruby 2.5.
**To run the project locally**:
1. Install a full [Ruby development environment](https://jekyllrb.com/docs/installation/)
2. Install Jekyll and [bundler gems](https://jekyllrb.com/docs/ruby-101/#bundler)
Expand All @@ -12,72 +12,63 @@ The present version of AIMA-Exercises uses Jekyll 3 and ruby 2.5.
- [Windows](https://jekyllrb.com/docs/installation/windows/)
4. Clone the project locally.
5. Go to the folder directory where you cloned the project in terminal.
6. `gem install jekyll bundler `
6. `gem install jekyll bundler`
7. `bundle exec jekyll serve`

**The directory structure is as follows:**
* `_includes` - The include tag allows you to include the content from another file stored in the `_includes` folder and contains reusable files like `staticman_comments.html` which is the form used for submitting answers. Sidebar templates, head.html and breadcrumb.
* `_layouts` - They allow you to have the source code for project template in one place so you don’t have to repeat things like your navigation and footer on every page. The layouts folder has default layout, homepage layout, exercise layout, answersubmitted layout and others.
* `_site` - This is where the generated site is placed (by default) once Jekyll is done transforming it. While contributing, don't change files in the `_site` directory as Github Pages is compatible with Jekyll and `_site` folder is updated everytime the root directory folders are changed.
* `_includes` - The include tag allows you to include the content from another file stored in the `_includes` folder and contains reusable files like `staticman_comments.html` which is the form used for submitting answers. Sidebar templates, head.html, and breadcrumb.
* `_layouts` - They allow you to have the source code for project templates in one place so you don’t have to repeat things like your navigation and footer on every page. The layouts folder has default layout, homepage layout, exercise layout, answersubmitted layout, and others.
* `_site` - This is where the generated site is placed (by default) once Jekyll is done transforming it. While contributing, don't change files in the `_site` directory as GitHub Pages is compatible with Jekyll and the `_site` folder is updated every time the root directory folders are changed.
* `figures` - The figures folder contains figures for all the exercises.
* `js` - The JS folder contains the javascript codes for all the features. answer.js, bookmark.js , search.js , commsol.js, forms.js.
* `latex` - Latex folder contains latex files for all the exercises.
* `markdown` - `Markdown` folder contains markdown format of all the exercises along with the index.md files for generating the exercises pages and the answers folder (if any answer is present for that particular exercise). Each exercise has it's own `answers` folder.
* `public` - Public folder contains css files and fonts for the project.
* `search` - Search folder contains index.md file for rendering search results.
* `404.html` - 404 page when a person reaches a page which is not present in the directory.
* `Gemfile` - A Gemfile is a file we create which is used for describing gem dependencies for Ruby programs.The Gemfile is where you specify which gems you want to use, and lets you specify which versions.
* `js` - The JS folder contains JavaScript codes for all the features. answer.js, bookmark.js, search.js, commsol.js, forms.js.
* `latex` - The LaTeX folder contains LaTeX files for all the exercises.
* `markdown` - The `markdown` folder contains markdown format of all the exercises along with the index.md files for generating the exercises pages and the answers folder (if any answer is present for that particular exercise). Each exercise has its own `answers` folder.
* `public` - The public folder contains CSS files and fonts for the project.
* `search` - The search folder contains index.md file for rendering search results.
* `404.html` - 404 page when a person reaches a page that is not present in the directory.
* `Gemfile` - A Gemfile is a file we create which is used for describing gem dependencies for Ruby programs. The Gemfile is where you specify which gems you want to use and lets you specify which versions.
* `Gemfile.lock` - The `Gemfile.lock` file is where Bundler records the exact versions that were installed. This way, when the same library/project is loaded on another machine, running bundle install will look at the Gemfile.lock and install the exact same versions, rather than just using the Gemfile and installing the most recent versions.
* `.jekyll-metadata` - Incremental regeneration helps shorten build times by only generating documents and pages that were updated since the previous build. It does this by keeping track of both file modification times and inter-document dependencies in the `.jekyll-metadata` file.
* `LICENSE.md` - License file for aima exercises project. It is released under standard MIT License.
* `LICENSE.md` - License file for the AIMA exercises project. It is released under the standard MIT License.
* `README.md` - Readme file for the project.
* `_config.yml` - Configuration file used by jekyll for building the site.
* `index.html`- The front page of the aima exercises project.
* `_config.yml` - Configuration file used by Jekyll for building the site.
* `index.html` - The front page of the AIMA exercises project.
* `search_data.json` - Search data used by lunr.js for searching through the exercises. It's a script which takes into account all the exercises.
* `staticman.yml` - Staticman configuration file for sending automated Pull requests whenever a user submits an answer.
* `staticman.yml` - Staticman configuration file for sending automated Pull Requests whenever a user submits an answer.

**Contributions to the project can be made in the following ways:**

**Contributions to the project can be made in following ways:**
1. *Contribution towards building features for the project.*
- There are several features that still require attention.
- Improving the User interface of submitted answers.
- There are several features that still require attention:
- Improving the User Interface of submitted answers.
- Fixing Cross References.
- Feature to upvote/like an exercise or answer.
- Feature to extract a few questions in PDF format/Latex or markdown format.
- Adding a feature to upvote/like an exercise or answer.
- Adding a feature to extract a few questions in PDF format/LaTeX or markdown format.

2. *Submitting answers to various exercises.*
- Answer submission through the website itself.
- Answer submission through the website itself:
- Fill the form on various exercise layout pages.
- ![Screenshot from 2019-08-13 05-11-53](https://user-images.githubusercontent.com/34926285/62905620-f1b6c600-bd88-11e9-8421-c0aa4c0b2570.png)
- Filling the form will automatically send a Pull Request using @staticmanaima and if merged the answer would be visible under User answers column.
- `Community answer` is the answer provided by admin/moderators and is a verified solution. Community solution can be requested through the the exercise layout page and will be made available under special cases only.
- Answer submission through Github:
- Go to the exercise folder of the exercise which you are interested in submitting an answer for.
- Filling the form will automatically send a Pull Request using the Staticman configuration provided in the `staticman.yml` file. If merged, the answer will be visible under the User answers column.
- `Community answer` is the answer provided by admin/moderators and is a verified solution. Community solutions can be requested through the exercise layout page and will be made available under special cases only.
- Answer submission through GitHub:
- Go to the exercise folder of the exercise you are interested in submitting an answer for.
- Suppose you want to submit an answer to `Exercise 1` of Chapter 1 - `Introduction`.
- The exercises folders are present inside the `markdown` folder in root directory.
- The exercises folders are present inside the `markdown` folder in the root directory.
- Go to `markdown->1-Introduction->ex_1`
- If there is an answers folder present already in the exercise folder , go inside that folder. Else click on the Create New file .
- If there is an answers folder present already in the exercise folder, go inside that folder. Else click on the Create New file.
![Screenshot from 2019-08-13 05-21-44](https://user-images.githubusercontent.com/34926285/62905952-49096600-bd8a-11e9-8eb5-18e32a3c9501.png)
- Type `answers/` in the Create new file box.
- This will create a folder named `answers` inside the `ex_1` folder as shown.
![Screenshot from 2019-08-13 05-24-27](https://user-images.githubusercontent.com/34926285/62906033-a9000c80-bd8a-11e9-89c7-49cf56b5cd27.png)
- Name your file as answer-{Your-Github-Username{}.md. For example
- Name your file as `answer-{Your-Github-Username}.md`. For example:
- ![Screenshot from 2019-08-13 05-27-21](https://user-images.githubusercontent.com/34926285/62906136-0c8a3a00-bd8b-11e9-9630-f175d9a0eeaa.png)
- Note: If you are submitting a second answer through github make sure to add the answer number along with your Github username to avoid duplicate name files.
- For example, if I am submitting a second answer to same question my file name would be `answer-sachin10101998-2.md`.
- Your answer must have a specific template as mentioned below to get merged. make sure to follow the template while submitting the answer.
- Note: If you are submitting a second answer through GitHub, make sure to add the answer number along with your GitHub username to avoid duplicate name files.
- For example, if I am submitting a second answer to the same question, my file name would be `answer-sachin10101998-2.md`.
- Your answer must have a specific template as mentioned below to get merged. Make sure to follow the template while submitting the answer.
![Screenshot from 2019-08-13 05-33-00](https://user-images.githubusercontent.com/34926285/62906352-da2d0c80-bd8b-11e9-8e5d-cdeb3912f3ae.png)
- The template is as follows:
`---`
`Name: Your name`
`Email: Your email`
`---`
`Your answer here.`

If you still have any qeries/doubts regarding the project, feel free to join our [Gitter channel](https://gitter.im/aimacode/Lobby).
Feel free to create a new issue if you find any bugs in the project that requires our attention or you may even send a Pull Request for fixing it. :)








If you still have any queries or doubts regarding the project, feel free to join our [Gitter channel](https://gitter.im/aimacode/Lobby).
Feel free to create a new issue if you find any bugs in the project that require our attention, or you may even send a Pull Request for fixing it. :)