Rebuild docs: DRY edition
Point to the dependency management docs for general review guidelines and add docs for the freeze process. Story: 2003792 Task: 26500 Depends-On: https://review.openstack.org/615388 Change-Id: I5adb28faaeb19735445450c26bcf40ecd5336a9f
This commit is contained in:
Matthew Thode
parent
55f4a46035
commit
01ccedef0e
126
README.rst
126
README.rst
@ -1,126 +1,16 @@
|
||||
============================================
|
||||
Global Requirements for OpenStack Projects
|
||||
============================================
|
||||
===========================================================
|
||||
Global Requirements and Constraints for OpenStack Projects
|
||||
===========================================================
|
||||
|
||||
.. image:: https://governance.openstack.org/tc/badges/requirements.svg
|
||||
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
||||
|
||||
Why Global Requirements?
|
||||
========================
|
||||
Resources and Documentation
|
||||
===========================
|
||||
|
||||
Refer to the `Dependency Management`_ section of the *Project Team
|
||||
Guide* for information about the history of the project and the files
|
||||
involved.
|
||||
Please refer to the dependency management documentation linked below for up to
|
||||
date documentation on how to use and interact with the requirements project.
|
||||
|
||||
.. _Dependency Management: https://docs.openstack.org/project-team-guide/dependency-management.html
|
||||
|
||||
Tools
|
||||
=====
|
||||
|
||||
All the tools require openstack_requirements to be installed (e.g. in a Python
|
||||
virtualenv). They all have help, which is the authoritative documentation.
|
||||
|
||||
update-requirements
|
||||
-------------------
|
||||
|
||||
This will update the requirements in a project from the global requirements
|
||||
file found in ``.``. Alternatively, pass ``--source`` to use a different
|
||||
global requirements file::
|
||||
|
||||
update-requirements --source /opt/stack/requirements /opt/stack/nova
|
||||
|
||||
Entries in all requirements files will have their versions updated to match
|
||||
the entries listed in the global requirements. Excess entries will cause
|
||||
errors in hard mode (the default) or be ignored in soft mode.
|
||||
|
||||
generate-constraints
|
||||
--------------------
|
||||
|
||||
Compile a constraints file showing the versions resulting from installing all
|
||||
of ``global-requirements.txt``::
|
||||
|
||||
generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \
|
||||
-b blacklist.txt -r global-requirements.txt > new-constraints.txt
|
||||
|
||||
edit-constraints
|
||||
----------------
|
||||
|
||||
Replace all references to a package in a constraints file with a new
|
||||
specification. Used by DevStack to enable git installations of libraries that
|
||||
are normally constrained::
|
||||
|
||||
edit-constraints oslo.db "-e file://opt/stack/oslo.db#egg=oslo.db"
|
||||
|
||||
build-lower-constraints
|
||||
-----------------------
|
||||
|
||||
Combine multiple lower-constraints.txt files to produce a list of the
|
||||
highest version of each package mentioned in the files. This can be
|
||||
used to produce the "highest minimum" for a global lower constraints
|
||||
list (a.k.a., the "TJ Maxx").
|
||||
|
||||
To use the script, run::
|
||||
|
||||
$ tox -e venv -- build-lower-constraints input1.txt input2.txt
|
||||
|
||||
Where the input files are lower-constraints.txt or requirements.txt
|
||||
files from one or more projects.
|
||||
|
||||
If the inputs are requirements files, a lower constraints list for the
|
||||
requirements is produced. If the inputs are lower-constraints.txt, the
|
||||
output includes the highest version of each package referenced in the
|
||||
files.
|
||||
|
||||
check-requirements
|
||||
------------------
|
||||
|
||||
Run the validation checks from the ``requirements-check`` job locally
|
||||
using the ``requirements-check`` tox environment.
|
||||
|
||||
Run::
|
||||
|
||||
$ tox -e requirements-check -- /path/to/repo/to/test
|
||||
|
||||
Proposing changes
|
||||
=================
|
||||
|
||||
Look at the `Review Guidelines`_ and make sure your change meets them.
|
||||
|
||||
All changes to ``global-requirements.txt`` may dramatically alter the contents
|
||||
of ``upper-constraints.txt`` due to adding or removing transitive
|
||||
dependencies. As such you should always generate a diff against the current
|
||||
merged constraints, otherwise your change may fail if it is incompatible with
|
||||
the current tested constraints.
|
||||
|
||||
Regenerating involves five steps.
|
||||
|
||||
1) Install the dependencies needed to compile various Python packages::
|
||||
|
||||
sudo apt-get install $(bindep -b)
|
||||
|
||||
2) Create a reference file (do this without your patch applied)::
|
||||
|
||||
generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \
|
||||
-b blacklist.txt -r global-requirements.txt > baseline
|
||||
|
||||
3) Apply your patch and generate a new reference file::
|
||||
|
||||
generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \
|
||||
-b blacklist.txt -r global-requirements.txt > updated
|
||||
|
||||
4) Diff them::
|
||||
|
||||
diff -p baseline updated
|
||||
|
||||
5) Apply the patch to ``upper-constraints.txt``. This may require some
|
||||
fiddling. ``edit-constraint`` can do this for you **when the change
|
||||
does not involve multiple lines for one package**.
|
||||
|
||||
Resources
|
||||
=========
|
||||
|
||||
- Documentation: https://docs.openstack.org/requirements/latest/
|
||||
- Documentation: https://docs.openstack.org/project-team-guide/dependency-management.html
|
||||
- Wiki: https://wiki.openstack.org/wiki/Requirements
|
||||
- Bugs: https://launchpad.net/openstack-requirements
|
||||
|
||||
.. _Review Guidelines: https://docs.openstack.org/project-team-guide/dependency-management.html#review-guidelines
|
||||
|
||||
32
doc/source/freeze.rst
Normal file
32
doc/source/freeze.rst
Normal file
@ -0,0 +1,32 @@
|
||||
========================
|
||||
Openstack Freeze Process
|
||||
========================
|
||||
|
||||
PTL Actions
|
||||
===========
|
||||
|
||||
Notice
|
||||
++++++
|
||||
|
||||
- Email the developer mailing list approximately two weeks before the freeze.
|
||||
This email should contain a notice that requirements will branch and
|
||||
cycle-trailing projects should be careful if they have not branched. The
|
||||
cycle-trailing projects can retarget their constraints usage to the stable
|
||||
branch.
|
||||
|
||||
Branch
|
||||
++++++
|
||||
|
||||
- File a review in ``openstack/releases`` with -W and only remove the -W when
|
||||
ready to branch.
|
||||
|
||||
- Once branched, change the publish location to the new release branch.
|
||||
|
||||
- Once branched, update devstack grenade for the new release. For example,
|
||||
use https://review.openstack.org/#/c/493057/13/devstack-vm-gate-wrap.sh
|
||||
|
||||
Potential issues
|
||||
++++++++++++++++
|
||||
|
||||
- Use something like https://review.openstack.org/#/c/492382 to find problem
|
||||
projects.
|
||||
@ -1 +1,2 @@
|
||||
.. include:: ../../README.rst
|
||||
.. include:: freeze.rst
|
||||
|
||||
Loading…
Reference in New Issue
Block a user