mirror of https://github.com/MISP/MISP
new: [doc] Add doc on how MISP uses git
E. Cleopatra
GitHub
parent
876c43859b
commit
15bf0e0fc5
|
|
@ -0,0 +1,159 @@
|
|||
# How MISP Project uses git/GitHub
|
||||
|
||||
MISP issues and code are managed on [GitHub](https://github.com/MISP).
|
||||
This page focuses on aspects of GitHub usage that are specific to MISP.
|
||||
This workflow is not set in stone: it will evolve based on what we learn while using GitHub.
|
||||
For general GitHub usage information, see the [GitHub user documentation](https://docs.github.com/en/github).
|
||||
|
||||
## Getting started
|
||||
|
||||
To create your GitHub account, visit the [registration page](https://github.com/join) in a web browser.
|
||||
Then you will be allowed to open new issues, create merge requests, and fork your own copy of our repositories.
|
||||
|
||||
## Organisation
|
||||
|
||||
All of our repositories are available under the [MISP GitHub account](https://github.com/MISP).
|
||||
The main Git repository and most issues live in the [MISP/MISP repository](https://github.com/MISP/MISP).
|
||||
|
||||
We use git to maintain all code for MISP project. We have divided the project into several components, each of which has its own separate repository. For example:
|
||||
- `MISP.git` – The core MISP code.
|
||||
- `misp-taxonomies.git` – Taxonomies used in MISP taxonomy system and can be used by other information sharing tools.
|
||||
- `misp-galaxy.git` – Clusters and elements to attach to MISP events or attributes (like threat actors).
|
||||
- `misp-warninglists.git` – Warning lists to inform users of MISP about potential false-positives or other information in indicators.
|
||||
|
||||
MISP code is divided into many git repositories for the following reasons:
|
||||
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
|
||||
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
|
||||
- Code repositories represent also licensing boundaries. So, e.g. because misp-objects and PYMISP are maintained in two different repositories, it is possible to have the latter under a CC0 1.0 Universal license, while keeping the former under a simplified 2-BSD license.
|
||||
|
||||
### Git branches organisation
|
||||
|
||||
MISP development uses several branches:
|
||||
|
||||
- Version branch: This is the default branch, and it is named to reflect the latest MISP release. At the time of writing, the default branch is `2.4`
|
||||
- Topic branches: We use topic branches, sometimes called `fix-*` and `feature-*`, respectively aimed at fixing a single bug and implementing a single new feature. Once ready, a topic branch is merged into the appropriate branch (generally the default branch). Until it has been merged, a topic branch's history may be rewritten.
|
||||
|
||||
## How we use GitHub metadata
|
||||
|
||||
On GitHub, issues and merge requests have metadata.
|
||||
Being consistent in the use of GitHub metadata makes collective work smoother.
|
||||
|
||||
### Title and description
|
||||
The title should be a short but clear description of what this is about. Some people are case sensitive, please try to consider that.
|
||||
|
||||
### Status and resolution
|
||||
|
||||
Open issues can have up to one status label, preceded by the letter "S". Each label has a description of what it represents.
|
||||
See the [list of status labels](https://github.com/MISP/MISP/labels?q=S%3A+), along with their descriptions.
|
||||
|
||||
The main advantage of using these labels is to organize and visualize issues on Issue Boards.
|
||||
Using these labels accurately improves the team's workflow.
|
||||
|
||||
Closed issue may have up to one resolution label, preceded by the letter "R". See the [list of resolution labels](https://github.com/MISP/MISP/labels?q=R%3A+), along with their descriptions. When an issue does not fit into MISP's mission, we reject it by creating a comment explaining why it's being rejected, closing the issue and the `R: wontfix` label. When an issue is closed as a duplicate, we create a comment that mentions the other, duplicated issue and add the `R: duplicate` label. If the issue is closed without one of the specific resolutions or a comment, then it means, by default, that the issue in question was fixed or the requested enhancement was implemented.
|
||||
|
||||
### Assignee
|
||||
|
||||
We use the Assignee field in a way that helps us organize our work as a team, focus on what matters most currently, and avoid individual over-commitment & feelings of failure.
|
||||
To this aim, most tasks should be up for grabs for anyone who has spare capacity and the required skills.
|
||||
So in general, issues and merge requests should not be assigned to anyone.
|
||||
|
||||
This being said, we do assign them if at least one of these conditions is met:
|
||||
|
||||
- Someone is actively working on it.
|
||||
- The task is important and urgent.
|
||||
- The milestone is set to the next MISP release.
|
||||
- Only one of us can complete the task. This helps identify bottlenecks and over-commitment.
|
||||
|
||||
### Milestone
|
||||
|
||||
Sometimes, Milestones are treated as a commitment, that other MISP contributors should be able to rely on.
|
||||
Othertimes, it is use it as a pool of tasks they want to have on their short-term radar.
|
||||
|
||||
### Type of work
|
||||
|
||||
To indicate the type of work that's needed to complete the next step on an issue, we use labels whose name starts with T. See the [list of type of work labels](https://github.com/MISP/MISP/labels?q=t%3A) and their descriptions.
|
||||
|
||||
### Other labels
|
||||
See our [full list of labels](https://code.briarproject.org/groups/briar/-/labels) for other uncategorized labels we use.
|
||||
|
||||
## Relationships between issues
|
||||
|
||||
GitHub is a bit limited when it comes to expressing semantic relationships between issues. Here is how we can overcome these limitations.
|
||||
- Parent/subtask: Issues with the `T:meta` label indicate parent issues that have subtasks under it. In the child issues, a comment will be added mentioning the parent issue.
|
||||
- Related issues: Related issues can be listed either in the description or in a comment. Either way, this adds a message in the activity stream of the referenced issue, with a link to the referencing issue.
|
||||
|
||||
|
||||
## How to document progress
|
||||
|
||||
### Create and update issues
|
||||
|
||||
For details about labels, see [metadata](). If you are very certain to work on the issue, leave a comment expressing your interest or ask to be assigned to it to avoid duplicate work.
|
||||
|
||||
All the knowledge useful to the others should be kept on that issue, or at least linked from there.
|
||||
When committing changes that will resolve an issue once merged, please include #NNNN in the commit message, NNNN being the issue number. Then, GitHub will automatically reference this commit on the corresponding issue, once the branch is pushed to our Git repository. For example:
|
||||
|
||||
```
|
||||
chg: [doc] Fix spelling errors (#3120)
|
||||
```
|
||||
|
||||
### Report progress or failure
|
||||
|
||||
It is important to:
|
||||
- Keep the team informed of how you feel committed to issues assigned to you, and about the timeline you're envisioning.
|
||||
- Avoid individual over-commitment & feelings of failure.
|
||||
|
||||
If you don't think you will manage to work on an issue any time soon, it's often best to make this clear on the issue, or to de-assign yourself.
|
||||
|
||||
### How to propose, review, and merge changes
|
||||
|
||||
We use Pull Requests (aka. PRs) to propose, review, and merge changes.
|
||||
|
||||
You can comment on issues and pull requests. [Our code of conduct](https://briarproject.org/code-of-conduct/) applies.
|
||||
|
||||
|
||||
|
||||
### Requesting input from someone else
|
||||
|
||||
If you need input from someone else on an issue or pull request, ask your question in a comment there, mentioning them with their GitHub login name: @nick. GitHub will send them an email notification about it.
|
||||
|
||||
If you want to raise attention of every single member of a team, mention it with the name of the corresponding group: @xyz-team. GitHub will notify every member of this group.
|
||||
|
||||
### Acting upon input requests
|
||||
|
||||
It's important to provide requested information as quickly as you can, to make the MISP contribution process more efficient and enjoyable.
|
||||
|
||||
When input is requested from you on an issue or pull request with @nick:
|
||||
- GitHub may send you an email notification
|
||||
- Please ensure your GitHub email notification settings and your email setup allow you to receive and notice these messages.
|
||||
|
||||
When you receive such a request, if you cannot provide the requested input immediately, you're responsible for keeping track of this task, for example creating a new issue assigned to yourself, or using whatever personal organization tools work for you.
|
||||
|
||||
### Automatic integration and testing
|
||||
|
||||
MISP core uses CodeQL and LGTM for some code analysis and security checks. When you submit a PR, consider the results of checks. Ensure that your code builds without errors and fix failing checks.
|
||||
|
||||
The majority of the repositories within the MISP GitHub organisation includes automatic integration with [TravisCI](https://travis-ci.org/MISP).
|
||||
If you contribute and make a pull request, verify if your changes affect the result of the tests.
|
||||
Automatic integration is not perfect including Travis but it’s a quick way to catch new bugs or major issues in contribution.
|
||||
When you make a pull-request, TravisCI is automatically called. If there are failing checks, no worries, review the output at Travis (it’s not
|
||||
always you).
|
||||
|
||||
#### JSON validation for MISP libraries
|
||||
All JSON format (galaxy, taxonomies, objects or
|
||||
warning-lists) are described in a JSON Schema 3 .
|
||||
The TravisCI tests are including JSON validation (via jq) and
|
||||
validated with the associated JSON schema.
|
||||
How to contribute a JSON library (objects, taxonomies,
|
||||
galaxy or warning-list):
|
||||
I If you update a JSON library, don’t forget to run
|
||||
jq_all_the_things.sh. It’s fast and easy. If it fails, review your
|
||||
JSON.
|
||||
I Commit your code and make a pull-request.
|
||||
Documentations (in PDF and HTML format) for the librairies
|
||||
are automatically generated from the JSON via asciidoctor 4
|
||||
|
||||
### Access control
|
||||
|
||||
If you need to do something in GitHub and you appear to lack the needed credentials, please ask the MISP team to grant you more power.
|
||||
For example, you will need "Triage" access in order to add labels or assign issues. See [GitHub's access permissions documentation](https://docs.github.com/en/github/getting-started-with-github/access-permissions-on-github).
|
||||
|
||||
Loading…
Reference in New Issue