diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 76cfbc398c..5eeb1af622 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,18 +1,19 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps documented at: +The source repository for this project can be found at: + + https://opendev.org/openstack/horizon + +Pull requests submitted through GitHub are not monitored. + +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: + + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html + +Bugs should be filed on Launchpad: + +https://bugs.launchpad.net/horizon + +For more specific information about contributing to this repository, see the +horizon contributor guide: https://docs.openstack.org/horizon/latest/contributor/contributing.html - - or https://docs.openstack.org/infra/manual/developers.html - -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: - - https://docs.openstack.org/infra/manual/developers.html#development-workflow - -Pull requests submitted through GitHub will be ignored. - -Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/horizon diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 5cf4e51171..dca1be8c69 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -1,111 +1,138 @@ -================== -Contributing Guide -================== +============================ +So You Want to Contribute... +============================ -First and foremost, thank you for wanting to contribute! It's the only way -open source works! +For general information on contributing to OpenStack, please check out the +`contributor guide `_ to get started. +It covers all the basics that are common to all OpenStack projects: the accounts +you need, the basics of interacting with our Gerrit review system, how we +communicate as a community, etc. -Before you dive into writing patches, here are some of the basics: +Below will cover the more project specific information you need to get started +with horizon. +Project Resources +----------------- + +* Source code: https://opendev.org/openstack/horizon +* Documentation: https://docs.openstack.org/horizon/latest/ * Project page: https://launchpad.net/horizon * Bug tracker: https://bugs.launchpad.net/horizon -* Source code: https://github.com/openstack/horizon * Code review: https://review.opendev.org/#/q/project:openstack/horizon+status:open -* Continuous integration: - * Jenkins: https://jenkins.openstack.org - * Zuul: http://status.openstack.org/zuul -* IRC Channel: #openstack-horizon on Freenode. -Making Contributions -==================== +Communication +------------- -Getting Started +* IRC channel: ``#openstack-horizon`` at freenode + + Most active contributors are online at IRC while they are active, + so it would be the easiest way to contact the team directly. + Note that all IRC conversations are stored + `here `__. + +* Mailing list: + `openstack-discuss + `__ + with ``[horizon]`` tag. + + The mailing list would be a good place if you would like to discuss your + topic with the OpenStack community more broadly. Most OpenStack users, + operators and developers subscribe it and you can get useful feedbacks + from various perspectives. + +* Team meeting: + + The horizon team has a weekly meeting which covers all things related to + the horizon project like announcements, project priorities, community goals, + bugs and so on. + + There is the "On Demand Agenda" section at the end of the meeting, where + anyone can add a topic to discuss with the team. It is suggested to add + such topic to the On-Demand agenda in the "Weekly meeting" in + `horizon release priority etherpad + `__. + + * Time: http://eavesdrop.openstack.org/#Horizon_Team_Meeting + * Agenda: https://wiki.openstack.org/wiki/Meetings/Horizon + +Contacting the Core Team +------------------------ + +The list of the current core reviewers is found at +`gerrit `__. + +Most core reviewers are online in the IRC channel and +you can contact them there. + +New Feature Planning +-------------------- + +If you would like to add a new feature to horizon, file a blueprint +to https://blueprints.launchpad.net/horizon. You can find a template for a +blueprint at https://blueprints.launchpad.net/horizon/+spec/template. +The template is not a strict requirement but it would be nice to cover +a motivation and an approach of your blueprint. From the nature of GUI, +a discussion on UI design during a patch review could be more productive, +so there is no need to explain the detail of UI design in your blueprint +proposal. + +We don't have a specific deadline during a development cycle. You can propose a +feature any time. Only thing you keep in your mind is that we do not merge +features during the feature freeze period after the milestone 3 in each cycle. + +There are a number of unsupported OpenStack features in horizon. +Implementing such would be appreciated even if it is small. + +Task Tracking +------------- + +We track our tasks in `Launchpad `__. + +If you're looking for some smaller, please look through the list of bugs +and find what you think you can work on. If you are not sure the status of +a bug feel free to ask to the horizon team. We can help you. +Note that we recently do not maintain 'low-hanging-fruit' tag and some of +them with this tag are not simple enough. + +Reporting a Bug --------------- -We'll start by assuming you've got a working checkout of the repository (if -not then please see the :ref:`quickstart`). +You found an issue and want to make sure we are aware of it? +You can do so on `Launchpad `__. -Second, you'll need to take care of a couple administrative tasks: +Please file a bug first even if you already have a fix for it. +If you can reproduce the bug reliably and identify its cause +then it's usually safe to start working on it. +However, getting independent confirmation (and verifying that it's not a +duplicate) is always a good idea if you can be patient. -#. Create an account on Launchpad. -#. Sign the `OpenStack Contributor License Agreement`_ and follow the associated - instructions to verify your signature. -#. Join the `Horizon Developers`_ team on Launchpad. -#. Follow the `instructions for setting up git-review`_ in your - development environment. +Getting Your Patch Merged +------------------------- -Whew! Got all that? Okay! You're good to go. +All changes proposed to horizon require two +2 votes from the horizon core +reviewers before one of the core reviewers can approve a change by giving +"Workflow +1" vote. -.. _`OpenStack Contributor License Agreement`: https://wiki.openstack.org/CLA -.. _`Horizon Developers`: https://launchpad.net/~horizon -.. _`instructions for setting up git-review`: https://docs.openstack.org/infra/manual/developers.html#development-workflow +In general, all changes should be proposed along with at least unit test +coverage (python or JavaScript). Integration test support would be +appreciated. -Ways To Contribute ------------------- +More detailed guidelines for reviewers of patches are available at +`OpenDev Developer's Guide `__. -The easiest way to get started with Horizon's code is to pick a bug on -Launchpad that interests you, and start working on that. Bugs tagged as -``low-hanging-fruit`` are a good place to start. Alternatively, if there's an -OpenStack API feature you would like to see implemented in Horizon feel free -to try building it. +Project Team Lead Duties +------------------------ -If those are too big, there are lots of great ways to get involved without -plunging in head-first: +All common PTL duties are enumerated in the `PTL guide +`_. -* Report bugs, triage new tickets, and review old tickets on - the `bug tracker`_. -* Propose ideas for improvements via `Launchpad Blueprints`_, via the - mailing list on the project page, or on IRC. -* Write documentation! -* Write unit tests for untested code! -* Help improve the `User Experience Design`_ or contribute to the - `Persona Working Group`_. - -.. _`bug tracker`: https://bugs.launchpad.net/horizon -.. _`Launchpad Blueprints`: https://blueprints.launchpad.net/horizon -.. _`User Experience Design`: https://wiki.openstack.org/wiki/UX#Getting_Started -.. _`Persona Working Group`: https://wiki.openstack.org/wiki/Personas - -Choosing Issues To Work On --------------------------- - -In general, if you want to write code, there are three cases for issues -you might want to work on: - -#. Confirmed bugs -#. Approved blueprints (features) -#. New bugs you've discovered - -If you have an idea for a new feature that isn't in a blueprint yet, it's -a good idea to write the blueprint first, so you don't end up writing a bunch -of code that may not go in the direction the community wants. - -For bugs, open the bug first, but if you can reproduce the bug reliably and -identify its cause then it's usually safe to start working on it. However, -getting independent confirmation (and verifying that it's not a duplicate) -is always a good idea if you can be patient. - -After You Write Your Patch --------------------------- - -Once you've made your changes, there are a few things to do: - -* Make sure the unit tests and linting tasks pass by running ``tox`` -* Take a look at your patch in API profiler, i.e. how it impacts the - performance. See :doc:`topics/profiling`. -* Make sure your code is ready for translation: See :ref:`pseudo_translation`. -* Make sure your code is up-to-date with the latest master: - ``git pull --rebase`` -* Finally, run ``git review`` to upload your changes to Gerrit for review. - -The Horizon core developers will be notified of the new review and will examine -it in a timely fashion, either offering feedback or approving it to be merged. -If the review is approved, it is sent to Jenkins to verify the unit tests pass -and it can be merged cleanly. Once Jenkins approves it, the change will be -merged to the master repository and it's time to celebrate! +The horizon PTL is expected to coordinate and encourage the core reviewer team +and contributors for the success. The expectations for the core reviewer team +is documented at :doc:`policies/core-reviewers` and the PTL would play an +important role in this. Etiquette -========= +--------- The community's guidelines for etiquette are fairly simple: diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 3e77e95e61..d397de7aec 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -6,10 +6,10 @@ .. toctree:: :maxdepth: 2 + contributing intro policies/index quickstart - contributing testing tutorials/index topics/index diff --git a/doc/source/contributor/policies/core-reviewers.rst b/doc/source/contributor/policies/core-reviewers.rst index 729d294338..b4ac511cc2 100644 --- a/doc/source/contributor/policies/core-reviewers.rst +++ b/doc/source/contributor/policies/core-reviewers.rst @@ -2,14 +2,14 @@ Core Reviewer Team ================== -The Horizon Core Reviewer Team is responsible for many aspects of the -Horizon project. These include, but are not limited to: +The horizon core reviewer team is responsible for many aspects of the +horizon project. These include, but are not limited to: - Mentor community contributors in solution design, testing, and the review process - Actively reviewing patch submissions, considering whether the patch: - is functional - - fits the use-cases and vision of the project + - fits use cases and vision of the project - is complete in terms of testing, documentation, and release notes - takes into consideration upgrade concerns from previous versions - Assist in bug triage and delivery of bug fixes @@ -19,15 +19,15 @@ Horizon project. These include, but are not limited to: features are added - Answering questions and participating in mailing list discussions - Interfacing with other OpenStack teams +- Helping horizon plugin maintenances In essence, core reviewers share the following common ideals: - They share responsibility in the project's success in its mission. - They value a healthy, vibrant, and active developer and user community. - They have made a long-term, recurring time investment to improve the project. -- They spend their time doing what needs to be done to ensure the - project's success, not necessarily what is the most interesting or - fun. +- They spend their time doing what needs to be done to ensure the project's + success, not necessarily what is the most interesting or fun. - A core reviewer's responsibility doesn't end with merging code. Core Reviewer Expectations @@ -37,18 +37,16 @@ Members of the core reviewer team are expected to: - Attend and participate in the weekly IRC meetings (if your timezone allows) - Monitor and participate in-channel at #openstack-horizon -- Monitor and participate in [Horizon] discussions on the mailing list -- Participate in related design summit sessions at the OpenStack - Summits and Project Team Gatherings +- Monitor and participate in ``[horizon]`` discussions on the mailing list +- Participate in related design sessions at Project Team Gatherings (PTGs) - Review patch submissions actively and consistently -Please note in-person attendance at design summits, mid-cycles, and -other code sprints is not a requirement to be a core reviewer. -Participation can also include contributing to the design documents -discussed at the design sessions. +Please note in-person attendance at PTGs, mid-cycles, and other code sprints is +not a requirement to be a core reviewer. Participation can also include +contributing to the design documents discussed at the design sessions. -Active and consistent review of review activity, bug triage and other -activity will be performed monthly and fed back to the Core Reviewer Team +Active and consistent review of review activity, bug triage and other activity +will be performed periodically and fed back to the core reviewer team so everyone knows how things are progressing. Code Merge Responsibilities @@ -63,3 +61,16 @@ testing, upgrade impacts and interactions with other projects. It also means you pay attention to release milestones and understand if a patch you are merging is marked for the release, especially critical during the feature freeze. + +Horizon Plugin Maintenance +-------------------------- + +GUI supports for most OpenStack projects are achieved via horizon plugins. +The horizon core reviewer team has responsibility to help horizon plugin teams +from the perspective of horizon related changes as the framework, +for example, Django version bump, testing improvements, plugin interface +changes in horizon and so on. A member of the team is expected to send and +review patches related to such changes. + +Note that involvements in more works in horizon plugins are up to individuals +but it would be nice to be involved if you have time :)