From: Victor Julien Date: Tue, 16 Sep 2025 15:20:56 +0000 (+0200) Subject: doc: adjust for master to main rename X-Git-Tag: suricata-8.0.2~61 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fpull%2F13860%2Fhead;p=thirdparty%2Fsuricata.git doc: adjust for master to main rename --- diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml index e6832064ea..ec4cabfbf3 100644 --- a/.github/workflows/formatting.yml +++ b/.github/workflows/formatting.yml @@ -76,13 +76,13 @@ jobs: zlib1g-dev # Checking out the branch is not as simple as "checking out". # - # In case master has any new commits since we branched off, github will - # automatically add a "merge commit" from our branch to master and check + # In case main has any new commits since we branched off, github will + # automatically add a "merge commit" from our branch to main and check # this out instead of the original last commit on the branch. # # This screws up git clang-format as it'll also format the "merge commit" # and essentially report any formatting issues in the "merge commit". - # However, we really don't care about any of the new commits on master. + # However, we really don't care about any of the new commits on main. # # There are supposed to be ways to use with/ref to fix that and while # they work perfectly well for pull requests within the forked repo, none @@ -123,7 +123,7 @@ jobs: second_last_commit_sha=$(git log --pretty=%H -2 |tail -1) echo "$last_commit_subject" | grep -e "^Merge $second_last_commit_sha into [0-9a-fA-F]*$" > /dev/null 2>&1 if [ $? -eq 0 ]; then - # Last commit was a merge to master - ignore + # Last commit was a merge to main - ignore echo "Found github merge commit - checking out real last commit instead..." git checkout $second_last_commit_sha else diff --git a/README.md b/README.md index 657549be26..45831312ec 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Suricata [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/suricata.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:suricata) -[![codecov](https://codecov.io/gh/OISF/suricata/branch/master/graph/badge.svg?token=QRyyn2BSo1)](https://codecov.io/gh/OISF/suricata) +[![codecov](https://codecov.io/gh/OISF/suricata/branch/main/graph/badge.svg?token=QRyyn2BSo1)](https://codecov.io/gh/OISF/suricata) ## Introduction diff --git a/doc/GITGUIDE b/doc/GITGUIDE index 41b4059a3c..32232d375e 100644 --- a/doc/GITGUIDE +++ b/doc/GITGUIDE @@ -18,7 +18,7 @@ The following workflow is recommended by Evan and is the guideline for contribut 3. - Create a branch for your work. This will make a copy of the current branch (master) and name it "new_feature". Now you can work in this new branch without breaking the main one. + Create a branch for your work. This will make a copy of the current branch (main) and name it "new_feature". Now you can work in this new branch without breaking the main one. git checkout -b new_feature @@ -30,9 +30,9 @@ The following workflow is recommended by Evan and is the guideline for contribut 5. - When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the master branch. + When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the main branch. - git checkout master + git checkout main 6. @@ -45,11 +45,11 @@ The following workflow is recommended by Evan and is the guideline for contribut Switch back to your topic branch and integrate any new changes. The git rebase command will save your changes away, update the topic branch, and then reapply them. git checkout new_feature - git rebase master + git rebase main Warning! If you are sharing a branch, you must use: - git merge master + git merge main Rebase causes the commit layout to change and will confuse anyone you've shared this branch with. @@ -61,9 +61,9 @@ The following workflow is recommended by Evan and is the guideline for contribut 9. - Now, switch back to the master branch and merge your changes from the topic branch + Now, switch back to the main branch and merge your changes from the topic branch - git checkout master + git checkout main git merge new_feature 10. @@ -84,7 +84,7 @@ The following workflow is recommended by Evan and is the guideline for contribut git branch -d new_feature -When you're familiar with the workflow, you can use the rake tasks to help you out. For example, rake git will fetch the latest code from remote repo, rebase the current branch to master, fast-forward the changes to master and push the commits to the remote. This saves a lot of typing. Check rake -T git for all the git related tasks. +When you're familiar with the workflow, you can use the rake tasks to help you out. For example, rake git will fetch the latest code from remote repo, rebase the current branch to main, fast-forward the changes to main and push the commits to the remote. This saves a lot of typing. Check rake -T git for all the git related tasks. Taken from: http://rubinius.lighthouseapp.com/projects/5089/using-git diff --git a/doc/userguide/appendix/eve-schema.rst b/doc/userguide/appendix/eve-schema.rst index 1462fc6056..39984d964a 100644 --- a/doc/userguide/appendix/eve-schema.rst +++ b/doc/userguide/appendix/eve-schema.rst @@ -6,7 +6,7 @@ log files. This schema follows the `JSON Schema `_ specification and can be found in ``etc/schema.json``. If your distribution does not contain this file, it can be viewed online at -https://github.com/OISF/suricata/blob/master/etc/schema.json, but note +https://github.com/OISF/suricata/blob/main/etc/schema.json, but note that it is version-specific and may change between major versions of Suricata. diff --git a/doc/userguide/devguide/codebase/code-style.rst b/doc/userguide/devguide/codebase/code-style.rst index 5fb2074d0b..fe74705791 100644 --- a/doc/userguide/devguide/codebase/code-style.rst +++ b/doc/userguide/devguide/codebase/code-style.rst @@ -87,7 +87,7 @@ Formatting your branch's commits In case you have multiple commits on your branch already and forgot to format them you can fix that up as well. -The following command will format every commit in your branch off master and +The following command will format every commit in your branch off main and rewrite history using the existing commit metadata. Tip: Create a new version of your branch first and run this off the new version. @@ -108,8 +108,8 @@ formatting changes: # Or with script: $ scripts/clang-format.sh branch -Note the usage of ``first_commit_on_your_branch^``, not ``master``, to avoid picking up -new commits on ``master`` in case you've updated master since you've branched. +Note the usage of ``first_commit_on_your_branch^``, not ``main``, to avoid picking up +new commits on ``main`` in case you've updated main since you've branched. Check formatting ~~~~~~~~~~~~~~~~ @@ -755,7 +755,7 @@ Banned functions +------------+---------------+-----------+ Also, check the existing code. If yours is wildly different, it's wrong. -Example: https://github.com/oisf/suricata/blob/master/src/decode-ethernet.c +Example: https://github.com/oisf/suricata/blob/main/src/decode-ethernet.c Rust **** diff --git a/doc/userguide/devguide/codebase/testing.rst b/doc/userguide/devguide/codebase/testing.rst index 41cd88c810..2eea615b52 100644 --- a/doc/userguide/devguide/codebase/testing.rst +++ b/doc/userguide/devguide/codebase/testing.rst @@ -15,7 +15,7 @@ There are a few ways of testing Suricata: - **Static and dynamic analysis tools**: to help in finding bugs, memory leaks and other issues (like `scan-build `_, from `clang`, which is also used for our C formatting checks; or ASAN, which checks for memory issues); - **Fuzz testing**: especially good for uncovering existing, often non-trivial bugs. For more on how to fuzz test Suricata, check :doc:`fuzz-testing`; - **CI checks**: each PR submitted to the project's public repositories will be run against a suit of Continuous Integration - workflows, as part of our QA process. Those cover: formatting and commit checks; fuzz tests (CI Fuzz), and several builds. See our `github workflows `_ for details and those in + workflows, as part of our QA process. Those cover: formatting and commit checks; fuzz tests (CI Fuzz), and several builds. See our `github workflows `_ for details and those in action at ``_. .. note:: If you can run unit tests or other checks and report failures in our `issue tracker `_, that is rather useful and appreciated! @@ -40,7 +40,7 @@ given that the way to do so differs, depending on the language. Code Examples ^^^^^^^^^^^^^ -An example from the `DNS parser `_. This +An example from the `DNS parser `_. This checks that the given raw input (note the comments indicating what it means), once processed by ``dns_parse_name`` yields the expected result, including the unparsed portion. diff --git a/doc/userguide/devguide/contributing/backports-guide.rst b/doc/userguide/devguide/contributing/backports-guide.rst index 4d719a6c1d..b9bf287247 100644 --- a/doc/userguide/devguide/contributing/backports-guide.rst +++ b/doc/userguide/devguide/contributing/backports-guide.rst @@ -12,7 +12,7 @@ There are multiple versions of Suricata at any given time: * Old stable release For example, at the moment, there are 3 releases based on these Suricata branches: - * master: 8.0.0-dev, current development branch + * main: 8.0.0-dev, current development branch * main-7.0.x: major stable release (note we're changing our naming conventions) * master-6.0.x: old stable release @@ -33,7 +33,7 @@ issue should be backported, please let us know in the ticket or related PR. But sometimes we'll miss those. The general principle used to determine what will be backported is: - * security fixes (please see our `Security Policy `_) + * security fixes (please see our `Security Policy `_) * bug fixes * in some cases, new features are backported if there are sufficient reasons to backport a new feature. @@ -80,21 +80,21 @@ Therefore, we will be periodically reviewing: Then, also periodically, we will create backport issues from those items identified in the previous steps. When doing so, we will evaluate what are the -relevant target backport releases. Some issues reported against master or the +relevant target backport releases. Some issues reported against main or the current Suricata release may not apply to older releases. Git Backport Workflow --------------------- If you are working on a task that needs to be backported, only start the -backporting process once the PR for master has been merged. Then: +backporting process once the PR for main has been merged. Then: * *Identify the commit(s) needed* for the backport. Start with the PR that merged - the commits into master and select only the commits from the issue being + the commits into main and select only the commits from the issue being backported. * *Bring each commit into the new branch,* one at a time -- starting with the oldest commit. Use ``git cherry-pick -x commit-hash``, where ``commit-hash`` - is the hash to the commit already in master or main-7.0x that is being + is the hash to the commit already in main or main-7.0x that is being backported, as it maintains the linkage with said cherry-picked commit. * *Resolve conflicts:* Some of the cherry-picked commits may contain merge conflicts. If the conflicts are small, include the corrections in the @@ -108,7 +108,7 @@ backporting process once the PR for master has been merged. Then: .. Note:: Exceptions - Sometimes, the fix for master will not work for the stable or old releases. + Sometimes, the fix for main will not work for the stable or old releases. In such cases, the backporting process won't be through cherry-picking, but through actually implementing a fix for the specific version. diff --git a/doc/userguide/devguide/contributing/code-submission-process.rst b/doc/userguide/devguide/contributing/code-submission-process.rst index 78e50d3eeb..950506fcdc 100644 --- a/doc/userguide/devguide/contributing/code-submission-process.rst +++ b/doc/userguide/devguide/contributing/code-submission-process.rst @@ -62,7 +62,7 @@ A github pull request is actually just a pointer to a branch in your tree. GitHu #. Incremental pull requests need to describe changes since the last PR #. Link to the ticket(s) that are addressed to it. #. When fixing an issue, update the issue status to ``In Review`` after submitting the PR. -#. Pull requests are automatically tested using github actions (https://github.com/OISF/suricata/blob/master/.github/workflows/builds.yml). +#. Pull requests are automatically tested using github actions (https://github.com/OISF/suricata/blob/main/.github/workflows/builds.yml). Failing builds won't be considered and should be closed immediately. #. Pull requests that change, or add a feature should include a documentation update commit diff --git a/doc/userguide/devguide/contributing/contribution-process.rst b/doc/userguide/devguide/contributing/contribution-process.rst index 006fecf035..2db105bb77 100644 --- a/doc/userguide/devguide/contributing/contribution-process.rst +++ b/doc/userguide/devguide/contributing/contribution-process.rst @@ -10,7 +10,7 @@ Essentially, these are: #. Agree to and sign our :ref:`Contribution Agreement` #. Communicate early, and use the :ref:`preferred channels ` #. :ref:`claim-ticket` -#. :ref:`Fork from master ` +#. :ref:`Fork from main ` #. Follow our :ref:`Coding Style` #. Use our :ref:`documentation-style` #. Stick to our :ref:`commit guidelines` @@ -183,16 +183,16 @@ There are usually 2 or 3 active branches: * master-x.x.x (e.g. master-6.0.x) * main-x.x.x (e.g. main-7.0.x) - * master + * main -The ones with version numbers are stable branches. **master** is the development branch. +The ones with version numbers are stable branches. **main** is the development branch. The stable branch should only be worked on for important bug fixes or other needed :doc:`backports`. Those are mainly expected from more experienced contributors. Development of new features or large scale redesign is done in the development -branch. New development and new contributors should work with *master* except +branch. New development and new contributors should work with *main* except in very special cases - which should and would be discussed with us first. If in doubt, please reach out to us via :ref:`Redmine, Discord or @@ -298,7 +298,7 @@ When using these, indicate the portion to be highlighted by surrounding it with It is only necessary to invoke the role once per document. One can see these being invoked in our introduction to the rule language (see `Rules intro -`_). +`_). A rule example like:: diff --git a/doc/userguide/devguide/extending/app-layer/app-layer-frames.rst b/doc/userguide/devguide/extending/app-layer/app-layer-frames.rst index cee854c6f3..09c2423fb0 100644 --- a/doc/userguide/devguide/extending/app-layer/app-layer-frames.rst +++ b/doc/userguide/devguide/extending/app-layer/app-layer-frames.rst @@ -71,7 +71,7 @@ Though the steps are the same, there are a few differences when implementing fra Rust ---- -This section shows how Frame support is added in Rust, using examples from the `SIP parser `_, and the `telnet parser `_. +This section shows how Frame support is added in Rust, using examples from the `SIP parser `_, and the `telnet parser `_. **Define the frame types**. The frame types are defined as an enum. In Rust, make sure to derive from the ``AppLayerFrameType``: diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst index 8cda0ce7e6..95b15bc58b 100644 --- a/doc/userguide/devguide/extending/output/index.rst +++ b/doc/userguide/devguide/extending/output/index.rst @@ -23,7 +23,7 @@ applications using Suricata as a library. The Suricata source code contains an example plugin demonstrating how to hook into some of these APIs. See -https://github.com/OISF/suricata/blob/master/examples/plugins/c-custom-loggers/custom-logger.c. +https://github.com/OISF/suricata/blob/main/examples/plugins/c-custom-loggers/custom-logger.c. Packet Logging ~~~~~~~~~~~~~~ diff --git a/doc/userguide/devguide/libsuricata/index.rst b/doc/userguide/devguide/libsuricata/index.rst index 943cef6a25..9632a35a76 100644 --- a/doc/userguide/devguide/libsuricata/index.rst +++ b/doc/userguide/devguide/libsuricata/index.rst @@ -26,7 +26,7 @@ Application-layer plugins ~~~~~~~~~~~~~~~~~~~~~~~~~ Application layer plugins can be added as demonstrated by example -https://github.com/OISF/suricata/blob/master/examples/plugins/altemplate/ +https://github.com/OISF/suricata/blob/main/examples/plugins/altemplate/ The plugin code contains the same files as an application layer in the source tree: - alname.rs : entry point of protocol with its registration @@ -65,4 +65,4 @@ Known limitations are: .. attention:: A pure rust plugin needs to be compiled with ``RUSTFLAGS=-Clink-args=-Wl,-undefined,dynamic_lookup`` This is because the plugin will link dynamically at runtime the functions defined in Suricata runtime. -You can define this rust flag in a ``.cargo/config.toml`` file. \ No newline at end of file +You can define this rust flag in a ``.cargo/config.toml`` file. diff --git a/doc/userguide/install/ubuntu.rst b/doc/userguide/install/ubuntu.rst index 3b757b9f5a..347dfb401a 100644 --- a/doc/userguide/install/ubuntu.rst +++ b/doc/userguide/install/ubuntu.rst @@ -74,7 +74,7 @@ repository, the same procedures as above apply, just using another PPA, .. note:: - Please have in mind that this is packaged from our latest development git master + Please have in mind that this is packaged from our latest development git main and is therefore potentially unstable. We do our best to make others aware of continuing development and items diff --git a/doc/userguide/rules/rule-types.rst b/doc/userguide/rules/rule-types.rst index 96c99478a3..6d239cba0c 100644 --- a/doc/userguide/rules/rule-types.rst +++ b/doc/userguide/rules/rule-types.rst @@ -9,7 +9,7 @@ Rule Types and Categorization Once parsed, Suricata rules are categorized for performance and further processing (as different rule types will be handled by specific engine modules). The signature types are defined in `src/detect.h -`_: +`_: .. literalinclude:: ../../../src/detect.h :caption: src/detect.h @@ -62,7 +62,7 @@ The rule type will impact: This categorization is done taking into consideration the presence or absence of certain rule elements, as well as the type of keywords used. The categorization currently takes place in `src/detect-engine-build.c:void SignatureSetType() -`_. +`_. The ``SignatureSetType()`` overall flow is described below: @@ -173,7 +173,7 @@ Signature Properties -------------------- The `Action Scope` mentioned above relates to the Signature Properties, as seen in -`src/detect-engine.c `_: +`src/detect-engine.c `_: .. literalinclude:: ../../../src/detect-engine.c :caption: src/detect-engine.c @@ -293,7 +293,7 @@ Decoder Events Only Signatures that inspect broken or invalid packets. They expose Suricata decoding events. -For more examples check https://github.com/OISF/suricata/blob/master/rules/decoder-events.rules. +For more examples check https://github.com/OISF/suricata/blob/main/rules/decoder-events.rules. Example """"""" diff --git a/doc/userguide/unix-socket.rst b/doc/userguide/unix-socket.rst index e870096bb5..83b8ab5c8f 100644 --- a/doc/userguide/unix-socket.rst +++ b/doc/userguide/unix-socket.rst @@ -26,7 +26,7 @@ directory. Clients are implemented for some programming languages and can be used as code example to write custom scripts: -* Rust: https://github.com/OISF/suricata/blob/master/rust/suricatasc (version provided in Suricata 8+) +* Rust: https://github.com/OISF/suricata/blob/main/rust/suricatasc (version provided in Suricata 8+) * Python: https://github.com/OISF/suricata/blob/main-7.0.x/python/suricata/sc/suricatasc.py (Python version from older versions of Suricata) * Perl: https://github.com/aflab/suricatac (a simple Perl client with interactive mode) * C: https://github.com/regit/SuricataC (a Unix socket mode client in C without interactive mode) diff --git a/examples/plugins/c-custom-loggers/README.md b/examples/plugins/c-custom-loggers/README.md index 412cc4f2df..4a0b718a0b 100644 --- a/examples/plugins/c-custom-loggers/README.md +++ b/examples/plugins/c-custom-loggers/README.md @@ -25,7 +25,7 @@ Building a standalone plugin has the following dependencies: Modify the Makefile to use `libsuricata-config`. Before building this plugin you will need to build and install Suricata from the -git master branch and install the development tools and headers: +git main branch and install the development tools and headers: - `make install-library` - `make install-headers` diff --git a/examples/plugins/c-json-filetype/README.md b/examples/plugins/c-json-filetype/README.md index fa0ae8adf6..75c3982cf6 100644 --- a/examples/plugins/c-json-filetype/README.md +++ b/examples/plugins/c-json-filetype/README.md @@ -21,7 +21,7 @@ Building a standalone plugin has the following dependencies: Modify the Makefile to use `libsuricata-config`. Before building this plugin you will need to build and install Suricata from the -git master branch and install the development tools and headers: +git main branch and install the development tools and headers: - `make install-library` - `make install-headers`