MISP
/
misp-book
mirror of https://github.com/MISP/misp-book
2
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #281 from SteveClement/main

pull/284/head
Steve Clement 2022-06-02 21:32:02 +09:00 committed by GitHub
parent 0a8f3f9f77 0b813c67a0
commit 3b711841cd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/workflows/honkit.yml vendored
View File

@ -4,7 +4,7 @@ on: [push]
jobs: jobs:
build: build:
runs-on: ubuntu-latest runs-on: ubuntu-22.04
strategy: strategy:
max-parallel: 4 max-parallel: 4
steps: steps:
@ -63,4 +63,6 @@ jobs:
- name: Run honkit mobi - name: Run honkit mobi
run: | run: |
npx honkit mobi npx honkit mobi
# npx honkit pdf SKIPPED as of 20220601 it fails but generic/epub/mobi passes - name: Run honkit pdf
run: |
npx honkit pdf

34
CONTRIBUTING.md
View File

@ -1,25 +1,25 @@
# Contributing to MISP Book # Contributing to MISP Book
Most of MISP's documentation pages are stored as plain text files in this dedicated misp-book repository. Most of MISP's documentation pages are stored as plain text files in this dedicated misp-book repository.
MISP Book is generic documentation for MISP including usage, API documentation, best practices, and specific configuration settings. MISP Book is generic documentation for MISP including usage, API documentation, best practices, and specific configuration settings.
The installation guides are held in the [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. The installation guides are held in the [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively.
By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of MISP documentation rather than relying solely on the web. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of MISP documentation rather than relying solely on the web.
MISP book is generated in HTML, PDF, epub, and mobi using [Honkit](https://github.com/honkit/honkit), which is a framework to write documentation in Markdown format. MISP book is generated in HTML, PDF, epub, and mobi using [Honkit](https://github.com/honkit/honkit), which is a framework to write documentation in Markdown format.
The documentation is regularly published on [misp-project.org](https://www.misp-project.org/) and [circl.lu website](https://www.circl.lu/doc/misp/). The documentation is regularly published on [misp-project.org](https://www.misp-project.org/) and [circl.lu website](https://www.circl.lu/doc/misp/).
## Documentation guidelines ## Documentation guidelines
The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive. The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
If you notice a problem or some way it can be improved, please edit the documentation. If you notice a problem or some way it can be improved, please edit the documentation.
All pull requests against MISP must pass review before being merged. All pull requests against MISP must pass review before being merged.
This process is designed to ensure that contributed text is accurate and non-malicious. This process is designed to ensure that contributed text is accurate and non-malicious.
Once a pull request passes review, the documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts or broken links). Once a pull request passes review, the documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts or broken links).
If so, the documentation maintainer then merges the pull request. If so, the documentation maintainer then merges the pull request.
If you have a question about something you read in the documentation, you may ask into the [Gitter Support channel](https://gitter.im/MISP/Support) or open an issue for it. If you have a question about something you read in the documentation, you may ask into the [Gitter Support channel](https://gitter.im/MISP/Support) or open an issue for it.
If you see that something in the documentation should be fixed or improved, please [contribute the change](#how-to-make-a-contributution) yourself. If you see that something in the documentation should be fixed or improved, please [contribute the change](#how-to-make-a-contributution) yourself.
## How to make a contribution ## How to make a contribution
@ -28,19 +28,19 @@ Editing the documentation is easy, so if you see that a change should be made, p
A few notes before we get started: A few notes before we get started:
- Every documentation change will be reviewed before it’s accepted. This allows us to maintain quality control and protect our users. - Every documentation change will be reviewed before it’s accepted. This allows us to maintain quality control and protect our users.
- If your contribution would take a lot of time, please [file an issue](https://github.com/MISP/misp-book/issues) for it first so that we can make sure we’re on the same page before significant work begins. This ensures you do not spend time and effort on a contribution that we can’t accept. - If your contribution would take a lot of time, please [file an issue](https://github.com/MISP/misp-book/issues) for it first so that we can make sure we’re on the same page before significant work begins. This ensures you do not spend time and effort on a contribution that we can’t accept.
Thanks to GitHub’s interface, you can edit MISP's documentation even if you don’t know git at all. Thanks to GitHub’s interface, you can edit MISP's documentation even if you don’t know git at all.
All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [misp-book repo](https://github.com/MISP/misp-book/), make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/)). All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [misp-book repo](https://github.com/MISP/misp-book/), make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/)).
You can also [open issues](https://github.com/MISP/misp-book/issues) if you find any errors or propose changes. You can also [open issues](https://github.com/MISP/misp-book/issues) if you find any errors or propose changes.
[TravisCI](https://travis-ci.org/MISP) (used for automatic integration) is included in misp-book and the book generation is tested at each commit. [GitHub workflows](https://docs.github.com/en/actions/using-workflows) (used for automatic integration) is included in misp-book and the book generation is tested at each commit.
When you make a pull request, verify if your changes affect the result of the tests. When you make a pull request, verify if your changes affect the result of the tests.
If the checks fail, review the output at Travis and make fixes where possible. If the checks fail, review the output at Travis and make fixes where possible.
### For native English speakers ### For native English speakers
Most MISP developers are not native English speakers so you're more than welcome to correct or improve our English. Most MISP developers are not native English speakers so you're more than welcome to correct or improve our English.
For this, you can either submit a pull request or use another way that suits you better to share your improvements with us. For this, you can either submit a pull request or use another way that suits you better to share your improvements with us.
@ -48,7 +48,7 @@ For this, you can either submit a pull request or use another way that suits you
- Do not duplicate documentation. Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated at some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than one place). Such traps are often more harmful than if the documentation never existed in the first place. The solution is to link to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare. - Do not duplicate documentation. Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated at some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than one place). Such traps are often more harmful than if the documentation never existed in the first place. The solution is to link to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
- We maintain only one set of documentation for MISP. We do not maintain a different set of documentation for each version of MISP. Our single set of MISP documentation is updated on a continual, rolling basis. Our first priority is to document all current, stable releases of MISP. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. - We maintain only one set of documentation for MISP. We do not maintain a different set of documentation for each version of MISP. Our single set of MISP documentation is updated on a continual, rolling basis. Our first priority is to document all current, stable releases of MISP. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
- Instructions on how to install MISP are held in [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. - Instructions on how to install MISP are held in [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively.
## Style guidelines ## Style guidelines