openstack/oslo.policy
Code Issues Proposed changes

Fix grammar issues

Browse Source 
Change-Id: I138e5cf6deb82ad29a2bf70392c1859354b84800
This commit is contained in:
Qi Zhang
2020-10-27 22:15:02 -07:00
parent 266ee36d33
commit 96cfafb261
5 changed files with 19 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CONTRIBUTING.rst
View File

@ -1,10 +1,10 @@
If you would like to contribute to the development of oslo's libraries, If you would like to contribute to the development of oslo's libraries,
first you must take a look to this page: first you must take a look at this page:
https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html
If you would like to contribute to the development of OpenStack, If you would like to contribute to the development of OpenStack,
you must follow the steps in this page: you must follow the steps on this page:
https://docs.openstack.org/infra/manual/developers.html https://docs.openstack.org/infra/manual/developers.html

4
doc/source/configuration/index.rst
View File

@ -3,7 +3,7 @@
======================= =======================
oslo.policy uses oslo.config to define and manage configuration options oslo.policy uses oslo.config to define and manage configuration options
to allow the deployer to control where the policy files are located and that allow the deployer to control where the policy files are located,
the default rule to apply when policy etc. the default rule to apply, etc.
.. show-options:: oslo.policy .. show-options:: oslo.policy

2
doc/source/user/plugins.rst
View File

@ -35,7 +35,7 @@ entry point and will try to invoke that stevedore plugin.
This mechanism allows anyone to write their own code, in their own library This mechanism allows anyone to write their own code, in their own library
with their own custom stevedore based rule check plugins and can enhance with their own custom stevedore based rule check plugins and can enhance
their policies with custom checks. This would be useful for example to their policies with custom checks. This would be useful for example to
integrate with a in-house policy server. integrate with an in-house policy server.
Example code - HttpCheck Example code - HttpCheck

6
doc/source/user/sphinxpolicygen.rst
View File

@ -23,7 +23,7 @@ where:
``policy_generator_config_file`` ``policy_generator_config_file``
Path to an configuration file used with the ``oslopolicy-sample-generator`` Path to an configuration file used with the ``oslopolicy-sample-generator``
utility. This can be an full path or a value relative to the documentation utility. This can be a full path or a value relative to the documentation
source directory (``app.srcdir``). If this option is not specified or is source directory (``app.srcdir``). If this option is not specified or is
invalid then the sample policy file generation will be skipped. invalid then the sample policy file generation will be skipped.
@ -34,8 +34,8 @@ where:
``sample_policy_basename`` ``sample_policy_basename``
Base name of the output file. This name will be appended with a Base name of the output file. This name will be appended with a
``.policy.yaml.sample`` extension to generate the final output file and the ``.policy.yaml.sample`` extension to generate the final output file, and the
path is relative to documentation source directory (``app.srcdir``). As such, path is relative to the documentation source directory (``app.srcdir``). As such,
using the above example, the policy file will be output to using the above example, the policy file will be output to
``_static/nova.policy.yaml.sample``. If this option is not specified, the ``_static/nova.policy.yaml.sample``. If this option is not specified, the
file will be output to ``sample.policy.yaml``. file will be output to ``sample.policy.yaml``.

21
doc/source/user/usage.rst
View File

@ -19,8 +19,8 @@ Incorporating oslo.policy tooling
The ``oslo.policy`` library offers a generator that projects can use to render The ``oslo.policy`` library offers a generator that projects can use to render
sample policy files, check for redundant rules or policies, among other things. sample policy files, check for redundant rules or policies, among other things.
This is a useful tool not only for operators managing policies, but also This is a useful tool not only for operators managing policies but also for
developers looking to automate documentation describing the projects default developers looking to automate documentation describing projects' default
policies. policies.
This part of the document describes how you can incorporate these features into This part of the document describes how you can incorporate these features into
@ -39,7 +39,7 @@ First, you'll need to expose a couple of entry points in the project's
foo = foo.common.policy:get_enforcer foo = foo.common.policy:get_enforcer
The ``oslo.policy`` library uses the project namespace to call ``list_rules``, The ``oslo.policy`` library uses the project namespace to call ``list_rules``,
which should return a list of ``oslo.policy`` objects, either instances of which should return a list of ``oslo.policy`` objects, instances of either
``RuleDefault`` or ``DocumentedRuleDefault``. ``RuleDefault`` or ``DocumentedRuleDefault``.
The second entry point allows ``oslo.policy`` to generate complete policy from The second entry point allows ``oslo.policy`` to generate complete policy from
@ -129,7 +129,7 @@ benefits.
providing better documentation. providing better documentation.
* A sample policy file can be generated based on the registered policies * A sample policy file can be generated based on the registered policies
rather than needing to manually maintain one. rather than needing to be manually maintained.
* A policy file can be generated which is a merge of registered defaults and * A policy file can be generated which is a merge of registered defaults and
policies loaded from a file. This shows the effective policy in use. policies loaded from a file. This shows the effective policy in use.
@ -174,7 +174,7 @@ class::
The `DocumentedRuleDefault` class inherits from the `RuleDefault` The `DocumentedRuleDefault` class inherits from the `RuleDefault`
implementation, but it must be supplied with the `description` attribute in implementation, but it must be supplied with the `description` attribute in
order to be used. In addition, the `DocumentedRuleDefault` class requires a new order to be used. In addition, the `DocumentedRuleDefault` class requires a new
`operations` attributes that is a list of dictionaries. Each dictionary must `operations` attribute that is a list of dictionaries. Each dictionary must
have a `path` and a `method` key. The `path` should map to the path used to have a `path` and a `method` key. The `path` should map to the path used to
interact with the resource the policy protects. The `method` should be the HTTP interact with the resource the policy protects. The `method` should be the HTTP
verb corresponding to the `path`. The list of `operations` can be supplied with verb corresponding to the `path`. The list of `operations` can be supplied with
@ -269,9 +269,9 @@ Putting it all together
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Now that you know what services types, resources, attributes, and actions are Now that you know what services types, resources, attributes, and actions are
within the context of policy names, let establish the order you should use within the context of policy names, it is possible to establish the order you
them. Policy names should increase in detail as you read it. This results in should use them. Policy names should increase in detail as you read it. This
the following syntax:: results in the following syntax::
<service-type>:<resource>[:<subresource>][:<attribute>]:<action>[:<subaction>] <service-type>:<resource>[:<subresource>][:<attribute>]:<action>[:<subaction>]
@ -341,7 +341,8 @@ for a user with a project-scoped token to access a system-level API.
Developers incorporating `scope_types` into OpenStack services should be Developers incorporating `scope_types` into OpenStack services should be
mindful of the relationship between the API they are protecting with a policy mindful of the relationship between the API they are protecting with a policy
and if it operates on system-level resources or project-level resources. and the resource level the API operates at, whether it's system-level or
project-level.
Sample file generation Sample file generation
---------------------- ----------------------
@ -475,7 +476,7 @@ which determines if a user is allowed to do something.
The coupling between the authorization context, ultimately the token, and the The coupling between the authorization context, ultimately the token, and the
policy enforcement mechanism raises the bar for effectively testing policies policy enforcement mechanism raises the bar for effectively testing policies
and APIs. Service developers want to ensure the functionality specific to their and APIs. Service developers want to ensure the functionality specific to their
service works, and not dwell on the implementation details of an authorization service works and not dwell on the implementation details of an authorization
system. Additionally, they want to keep unit tests lightweight, as opposed to system. Additionally, they want to keep unit tests lightweight, as opposed to
requiring a separate system to issue tokens for authorization, crossing the requiring a separate system to issue tokens for authorization, crossing the
boundary of unit testing to integration testing. boundary of unit testing to integration testing.