From 5733db4dc8b42e13961581d1065f91f43b4d3be0 Mon Sep 17 00:00:00 2001 From: Emin Kocan Date: Mon, 16 Jun 2025 16:51:04 +0200 Subject: [PATCH] Restructure CONTRIBUTING.md and CONFIGURE.md --- CONFIGURE.md | 325 +++++++++++++++++++++++++++++++----------------- CONTRIBUTING.md | 220 +++++++++++++++++--------------- 2 files changed, 330 insertions(+), 215 deletions(-) diff --git a/CONFIGURE.md b/CONFIGURE.md index cc4daf02f..4397cd368 100644 --- a/CONFIGURE.md +++ b/CONFIGURE.md @@ -1,160 +1,261 @@ # Configuration -After [installing](INSTALL.md) this software, you may need to carry out some of these configuration steps, depending on your tasks. +After [installing](INSTALL.md) the OpenStreetMap website, you may need to carry out some configuration steps depending on your development tasks. -## Application configuration +## Table of Contents -Many settings are available in `config/settings.yml`. You can customize your installation of `openstreetmap-website` by overriding these values using `config/settings.local.yml` +1. [Prerequisites](#prerequisites) +2. [Basic Application Configuration](#basic-application-configuration) +3. [Database Population](#database-population) +4. [User Management](#user-management) +5. [OAuth Setup](#oauth-setup) +6. [Development Tools](#development-tools) +7. [Production Deployment](#production-deployment) +8. [Troubleshooting](#troubleshooting) -## Populating the database +## Prerequisites -Your installation comes with no geographic data loaded. You can either create new data using one of the editors (iD, JOSM etc) or by loading an OSM extract. +Before proceeding with configuration, ensure you have: +- Completed the [installation steps](INSTALL.md) +- Successfully started the Rails server +- Verified the website loads at [http://localhost:3000](http://localhost:3000) -After installing but before creating any users or data, import an extract with [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and the [``--write-apidb``](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--write-apidb_.28--wd.29) task. +## Basic Application Configuration -``` +### Application Settings + +Many settings are available in `config/settings.yml`. You can customize your installation of `openstreetmap-website` by overriding these values using `config/settings.local.yml`. + +## Database Population + +Your installation comes with no geographic data loaded. Before adding any data using one of the editors (iD, JOSM etc), you can optionally prepopulate the database using an OSM extract. + +### Loading Data with Osmosis (Optional) + +> [!NOTE] +> This step is entirely optional. You can start using the editors immediately to create new data, or if you prefer to work with existing data, you can import an extract with [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and the [`--write-apidb`](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--write-apidb_.28--wd.29) task. + +To import an extract, run: + +```bash osmosis --read-pbf greater-london-latest.osm.pbf \ --write-apidb host="localhost" database="openstreetmap" \ user="openstreetmap" password="" validateSchemaVersion="no" ``` -Loading an apidb database with Osmosis is about **twenty** times slower than loading the equivalent data with osm2pgsql into a rendering database. [``--log-progress``](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--log-progress_.28--lp.29) may be desirable for status updates. +> [!IMPORTANT] +> - Loading an apidb database with Osmosis is about **twenty** times slower than loading the equivalent data with osm2pgsql into a rendering database +> - [`--log-progress`](https://wiki.openstreetmap.org/wiki/Osmosis/Detailed_Usage#--log-progress_.28--lp.29) may be desirable for status updates +> - To be able to edit the data you have loaded, you will need to use this [yet-to-be-written script](https://github.com/openstreetmap/openstreetmap-website/issues/282) -To be able to edit the data you have loaded, you will need to use this [yet-to-be-written script](https://github.com/openstreetmap/openstreetmap-website/issues/282). +## User Management -## Managing Users +After creating a user through the web interface at [http://localhost:3000/user/new](http://localhost:3000/user/new), you may need to perform additional user management tasks. -If you create a user by signing up to your local website, you need to confirm the user before you can log in, which normally happens by clicking a link sent via email. If don't want to set up your development box to send emails to public email addresses then you can create the user as normal and then confirm it manually through the Rails console: +> [!TIP] +> If you don't want to set up your development box to send emails, you can manually confirm users and grant permissions through the Rails console. -``` -$ bundle exec rails console ->> user = User.find_by(:display_name => "My New User Name") -=> #[ ... ] ->> user.activate! -=> true ->> quit -``` +### Managing Users via Rails Console -### Giving Administrator/Moderator Permissions +1. **Enter the Rails console:** + ```bash + $ bundle exec rails console + ``` -To give administrator or moderator permissions: +2. **Find the user:** + ```ruby + >> user = User.find_by(:display_name => "My New User Name") + => #[ ... ] + ``` -``` -$ bundle exec rails console ->> user = User.find_by(:display_name => "My New User Name") -=> #[ ... ] ->> user.roles.create(:role => "administrator", :granter_id => user.id) -=> #[ ... ] ->> user.roles.create(:role => "moderator", :granter_id => user.id) -=> #[ ... ] ->> quit -``` +3. **Modify the user as desired:** -## OAuth Consumer Keys + **Activate/confirm the user:** + ```ruby + >> user.activate! + => true + ``` -There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are: + **Grant moderator role:** + ```ruby + >> user.roles.create(:role => "moderator", :granter_id => user.id) + => #[ ... ] + ``` -* iD -* The website itself (for the Notes functionality) + **Grant administrator role:** + ```ruby + >> user.roles.create(:role => "administrator", :granter_id => user.id) + => #[ ... ] + ``` -You can register them by running the following rake task: +4. **Exit the Rails console:** + ```ruby + >> quit + ``` -``` -bundle exec rails oauth:register_apps["My New User Name"] -``` +## OAuth Setup + +There are two built-in applications which communicate via the API, and therefore need to be registered as OAuth 2 applications. These are: -This task registers the applications with the "My New User Name" user as the owner -and saves their keys to `config/settings.local.yml`. When logged in, the owner should be able to see the apps on the [OAuth 2 applications](http://127.0.0.1:3000/oauth2/applications) page. +* **iD** - the web-based editor +* **The website itself** - for the Notes functionality + +### Automated OAuth Setup (Recommended) + +> [!TIP] +> You can register both applications automatically by running the following rake task: +> +> ```bash +> bundle exec rails oauth:register_apps["My New User Name"] +> ``` +> +> This task registers the applications with the "My New User Name" user as the owner and saves their keys to `config/settings.local.yml`. When logged in, the owner should be able to see the apps on the OAuth 2 applications page. Alternatively you can register the applications manually, as described in the next section. -### Manually registering the build-in OAuth applications - -For iD, do the following: - -* Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page. -* Click on "Register new application". -* Unless you have set up alternatives, use Name: "Local iD" and Redirect URIs: "http://localhost:3000" -* Check boxes for the following Permissions - * 'Read user preferences' - * 'Modify user preferences' - * 'Modify the map' - * 'Read private GPS traces' - * 'Upload GPS traces' - * 'Modify notes' -* On the next page, copy the "Client ID" -* Edit config/settings.local.yml in your rails tree -* Add the "id_application" configuration with the "Client ID" as the value -* Restart your rails server - -An example excerpt from settings.local.yml: - -```yaml -# Default editor -default_editor: "id" -# OAuth 2 Client ID for iD -id_application: "Snv…OA0" +### Setting up OAuth for iD + +1. **Navigate to OAuth applications:** + - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page + +2. **Register new application:** + - Click on "Register new application" + - **Name:** "Local iD" + - **Redirect URIs:** "http://localhost:3000" (unless you have set up alternatives) + +3. **Select permissions:** + Check boxes for the following: + - ✅ 'Read user preferences' + - ✅ 'Modify user preferences' + - ✅ 'Modify the map' + - ✅ 'Read private GPS traces' + - ✅ 'Upload GPS traces' + - ✅ 'Modify notes' + +4. **Configure the application:** + - Copy the "Client ID" from the next page + - Edit `config/settings.local.yml` in your rails tree + - Add the "id_application" configuration with the "Client ID" as the value + - Restart your rails server + +> [!TIP] +> **Example configuration in `settings.local.yml`:** +> ```yaml +> # Default editor +> default_editor: "id" +> # OAuth 2 Client ID for iD +> id_application: "Snv…OA0" +> ``` + +### Setting up OAuth for Notes and Changeset Discussions + +To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work: + +1. **Register OAuth application for the website:** + - Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page + - Click on "Register new application" + - **Name:** "OpenStreetMap Web Site" + - **Redirect URIs:** "http://localhost:3000" + +2. **Select permissions:** + Check boxes for: + - ✅ 'Modify the map' + - ✅ 'Modify notes' + +3. **Configure the application:** + - Copy both the "Client Secret" and "Client ID" + - Edit `config/settings.local.yml` + - Add both configurations + - Restart your rails server + +> [!TIP] +> **Example configuration in `settings.local.yml`:** +> ```yaml +> # OAuth 2 Client ID for the web site +> oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg" +> # OAuth 2 Client Secret for the web site +> oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI" +> ``` + +## Development Tools + +### Viewing Rails Logs + +Rails has its own log. To inspect the log during development: + +```bash +tail -f log/development.log ``` -To allow [Notes](https://wiki.openstreetmap.org/wiki/Notes) and changeset discussions to work, follow a similar process, this time registering an OAuth 2 application for the web site: - -* Go to "[OAuth 2 applications](http://localhost:3000/oauth2/applications)" on the My settings page. -* Click on "Register new application". -* Use Name: "OpenStreetMap Web Site" and Redirect URIs: "http://localhost:3000" -* Check boxes for the following Permissions - * 'Modify the map' - * 'Modify notes' -* On the next page, copy the "Client Secret" and "Client ID" -* Edit config/settings.local.yml in your rails tree -* Add the "oauth_application" configuration with the "Client ID" as the value -* Add the "oauth_key" configuration with the "Client Secret" as the value -* Restart your rails server - -An example excerpt from settings.local.yml: - -```yaml -# OAuth 2 Client ID for the web site -oauth_application: "SGm8QJ6tmoPXEaUPIZzLUmm1iujltYZVWCp9hvGsqXg" -# OAuth 2 Client Secret for the web site -oauth_key: "eRHPm4GtEnw9ovB1Iw7EcCLGtUb66bXbAAspv3aJxlI" -``` +### Maintaining Your Installation -## Troubleshooting +> [!TIP] +> If your installation stops working for some reason: +> +> - **Update gems:** Sometimes the bundle has been updated. Go to your `openstreetmap-website` directory and run: +> ```bash +> bundle install +> ``` +> +> - **Update Node.js modules:** If Node.js modules have been updated, run: +> ```bash +> bundle exec bin/yarn install +> ``` +> +> - **Run database migrations:** The OSM database schema is changed periodically. To keep up with improvements: +> ```bash +> bundle exec rails db:migrate +> ``` -Rails has its own log. To inspect the log, do this: +## Production Deployment -``` -tail -f log/development.log -``` +If you want to deploy `openstreetmap-website` for production use, you'll need to make several changes: -If you have more problems, please ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev) or on the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC) +### Web Server Configuration -## Maintaining your installation +> [!WARNING] +> Don't use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/). -If your installation stops working for some reason: +- Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation) +- Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts -* Sometimes gem dependencies change. To update go to your `openstreetmap-website` directory and run ''bundle install'' as root. +### Performance Optimizations -* The OSM database schema is changed periodically and you need to keep up with these improvements. Go to your `openstreetmap-website` directory and run: +> [!TIP] +> **Consider using CGIMap:** The included version of the map call is quite slow and eats a lot of memory. You should consider using [CGIMap](https://github.com/zerebubuth/openstreetmap-cgimap) instead. -``` -bundle exec rails db:migrate -``` +### Asset Compilation + +- **Generate i18n files and precompile assets:** + ```bash + RAILS_ENV=production bundle exec i18n export + bundle exec rails assets:precompile + ``` + +### File Permissions -## Testing on the osm dev server +> [!IMPORTANT] +> Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`. + +### Testing on the OSM Dev Server For example, after developing a patch for `openstreetmap-website`, you might want to demonstrate it to others or ask for comments and testing. To do this you can [set up an instance of openstreetmap-website on the dev server in your user directory](https://wiki.openstreetmap.org/wiki/Using_the_dev_server#Rails_Applications). -# Contributing +## Troubleshooting + +If you have problems with your configuration: + +- **Check the Rails log:** Use `tail -f log/development.log` to see what's happening +- **Verify database connectivity:** Ensure PostgreSQL is running and accessible +- **Check file permissions:** Make sure the Rails application can read/write necessary files +- **Review OAuth settings:** Ensure Client IDs and secrets are correctly configured -For information on contributing changes to the codes, see [CONTRIBUTING.md](CONTRIBUTING.md) +### Getting Help -# Production Deployment +If you need additional assistance: +- **Mailing list:** Ask on the [rails-dev@openstreetmap.org mailing list](https://lists.openstreetmap.org/listinfo/rails-dev) +- **IRC:** Join the [#osm-dev IRC Channel](https://wiki.openstreetmap.org/wiki/IRC) -If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes. +## Contributing -* It's not recommended to use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/). Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation). -* Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts. -* The included version of the map call is quite slow and eats a lot of memory. You should consider using [CGIMap](https://github.com/zerebubuth/openstreetmap-cgimap) instead. -* Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production bundle exec i18n export; bundle exec rails assets:precompile` -* Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`. +For information on contributing changes to the code, see [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20debf4d1..1dcbeaa66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,164 +1,178 @@ # Contributing +This guide covers our development workflow, coding standards, and how to get your changes merged. + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [How to Contribute](#how-to-contribute) +3. [Code Quality Guidelines](#code-quality-guidelines) +4. [Submitting Changes](#submitting-changes) +5. [Localization (i18n)](#localization-i18n) +6. [Copyright Attribution](#copyright-attribution) + +## Getting Started + +### Useful Resources + * https://www.ruby-lang.org/ - The homepage of Ruby which has more links and some great tutorials. * https://rubyonrails.org/ - The homepage of Rails, also has links and tutorials. -## Assigning Issues +### Finding Issues to Work On -We don't assign issues to individual contributors. You are welcome to work on any -issue, and there's no need to ask first. +> [!NOTE] +> We don't assign issues to individual contributors. You are welcome to work on any issue, and there's no need to ask first. -For more details see [our FAQ](FAQ.md)] +For more details see [our FAQ](FAQ.md) -## Coding style +## How to Contribute -We use [Rubocop](https://github.com/rubocop-hq/rubocop) (for ruby files) -and [ERB Lint](https://github.com/Shopify/erb-lint) (for erb templates) -to help maintain consistency in our code. You can run these utilities during -development to check that your code matches our guidelines: +Here's the typical contribution workflow: -``` +1. **Find an Issue**: Browse our [issues](https://github.com/openstreetmap/openstreetmap-website/issues) or identify a bug/feature you'd like to work on +2. **Fork & Clone**: Fork the repository and clone it to your local machine +3. **Set Up**: Follow the [installation guide](INSTALL.md) to set up your development environment +4. **Develop**: Make your changes following our [code quality guidelines](#code-quality-guidelines) +5. **Test**: Write tests for your changes and ensure all existing tests pass +6. **Commit**: Write clear commit messages following our [guidelines](#committing) +7. **Submit a Pull Request**: Create a pull request with a clear description of your changes + +## Code Quality Guidelines + +### Coding Style + +We use [Rubocop](https://github.com/rubocop-hq/rubocop) (for ruby files), [ESLint](https://eslint.org/) (for javascript files), and [ERB Lint](https://github.com/Shopify/erb-lint) (for erb templates) to help maintain consistency in our code. You can run these utilities during development to check that your code matches our guidelines: + +```bash bundle exec rubocop bundle exec rails eslint bundle exec erb_lint . ``` -You can also install hooks to have git run checks automatically when -you commit using [overcommit](https://github.com/sds/overcommit) with: +You can automatically fix many linting issues with: +```bash +bundle exec rubocop -a +bundle exec rails eslint:fix +bundle exec erb_lint . --autocorrect ``` -bundle exec overcommit --install -``` -## Testing +> [!NOTE] +> Use `bundle exec rails eslint:fix` instead of the standard `eslint --fix` option, which is silently ignored in this Rails project. + +> [!TIP] +> You can also install hooks to have git run checks automatically when you commit using [overcommit](https://github.com/sds/overcommit) with: +> +> ```bash +> bundle exec overcommit --install +> ``` -Having a good suite of tests is very important to the stability and -maintainability of any code base. The tests in the `openstreetmap-website` code are -by no means complete, but they are extensive, and must continue to be -so with any new functionality which is written. Tests are also useful -in giving others confidence in the code you've written, and can -greatly speed up the process of merging in new code. +### Testing + +> [!IMPORTANT] +> Having a good suite of tests is very important to the stability and maintainability of any code base. The tests in the `openstreetmap-website` code are by no means complete, but they are extensive, and must continue to be so with any new functionality which is written. Tests are also useful in giving others confidence in the code you've written, and can greatly speed up the process of merging in new code. When contributing, you should: * Write new tests to cover the new functionality you've added. -* Where appropriate, modify existing tests to reflect new or changed -functionality. -* Never comment out or remove a test just because it doesn't pass. +* Where appropriate, modify existing tests to reflect new or changed functionality. + +> [!WARNING] +> Never comment out or remove a test just because it doesn't pass. You can run the existing test suite with: -``` +```bash bundle exec rails test:all ``` You can run javascript tests with: -``` +```bash RAILS_ENV=test bundle exec teaspoon ``` You can view test coverage statistics by browsing the `coverage` directory. -The tests are automatically run on Pull Requests and other commits via github -actions. The results shown are within the PR display on github. +The tests are automatically run on Pull Requests and other commits via github actions. The results shown are within the PR display on github. -## Static Analysis +> [!TIP] +> **System tests** use Selenium with Firefox for browser automation. On Ubuntu 24.04, if Firefox is installed via snap, you may need to override the Firefox binary path in `config/settings.local.yml`: +> +> ```yaml +> system_test_firefox_binary: /snap/firefox/current/usr/lib/firefox/firefox +> ``` + +### Static Analysis We also perform static analysis of our code. You can run the analysis yourself with: -``` +```bash bundle exec brakeman -q ``` -## Comments +### Comments -Sometimes it's not apparent from the code itself what it does, or, -more importantly, **why** it does that. Good comments help your fellow -developers to read the code and satisfy themselves that it's doing the -right thing. +Sometimes it's not apparent from the code itself what it does, or, more importantly, **why** it does that. Good comments help your fellow developers to read the code and satisfy themselves that it's doing the right thing. When contributing, you should: -* Comment your code where necessary - explain the bits which -might be difficult to understand what the code does, why it does it -and why it should be the way it is. +* Comment your code where necessary - explain the bits which might be difficult to understand what the code does, why it does it and why it should be the way it is. * Check existing comments to ensure that they are not misleading. -## i18n +## Submitting Changes -If you make a change that involves the locale files (in `config/locales`) then please -only submit changes to the `en.yml` file. The other files are updated via -[Translatewiki](https://translatewiki.net/wiki/Translating:OpenStreetMap) and should -not be included in your pull request. +### Committing -### Copyright attribution +When you submit your changes, the project maintainers have to read them and understand them. This is difficult enough at the best of times, and misunderstanding commits can lead to them being more difficult to merge. To help with this, when committing you should: -The list of attributions on the /copyright page is managed by the [OSMF Licensing -Working Group (LWG)](https://wiki.osmfoundation.org/wiki/Licensing_Working_Group). +* Split up large commits into smaller units of functionality. +* Keep your commit messages relevant to the changes in each individual commit. -If you want to add another attribution, or make changes to the text of an existing -attribution, please follow these steps: +When writing commit messages please try and stick to the same style as other commits, namely: -* First, contact the LWG to discuss your proposed changes. -* If the LWG approves, please create a pull request with your proposed changes. -* Finally, please ask the LWG to formally approve the wording used in the pull request - (by having an LWG member comment on the PR). +* A one line summary, starting with a capital and with no full stop. +* A blank line. +* Full description, as proper sentences with capitals and full stops. -When we have formal confirmation from LWG, we can go ahead and merge the PR. +> [!TIP] +> Use the imperative verb form in your summary line (e.g., "Add feature" not "Added feature"). A good test is whether your summary line completes the sentence "This commit will...". For example: "This commit will **Fix user login validation**" or "This commit will **Update README installation steps**". -## Committing +For simple commits the one line summary is often enough and the body of the commit message can be left out. -When you submit your changes, the project maintainers have to read them and -understand them. This is difficult enough at the best of times, and -misunderstanding commits can lead to them being more difficult to -merge. To help with this, when committing you should: +### Pull Requests -* Split up large commits into smaller units of functionality. -* Keep your commit messages relevant to the changes in each individual -commit. +If you have forked on GitHub then the best way to submit your patches is to push your changes back to GitHub and open a Pull Request on GitHub. -When writing commit messages please try and stick to the same style as -other commits, namely: +If your pull request is small, for example one or two commits each containing only a few lines of code, then it is easy for the maintainers to review. -* A one line summary, starting with a capital and with no full stop. -* A blank line. -* Full description, as proper sentences with capitals and full stops. +> [!IMPORTANT] +> If you are creating a larger pull request, then please help the maintainers with making the reviews as straightforward as possible: +> +> * The smaller the PR, the easier it is to review. In particular if a PR is too large to review in one sitting, or if changes are requested, then the maintainer needs to repeatedly re-read code that has already been considered. +> * The commit history is important. This is a large codebase, developed over many years by many developers. We frequently need to read the commit history (for example using `git blame`) to figure out what is going on. So small, understandable, and relevant commits are important for other developers looking back at your work in future. + +> [!TIP] +> If you are creating a large pull request then please: +> +> * Consider splitting your pull request into multiple PRs. If part of your work can be considered standalone, or is a foundation for the rest of your work, please submit it separately first. +> * Avoid including "fixup" commits. If you have added a fixup commit (for example to fix a rubocop warning, or because you changed your own new code) please combine the fixup commit into the commit that introduced the problem. `git rebase -i` is very useful for this. +> * Avoid including "merge" commits. If your PR can no longer be merged cleanly (for example, an unrelated change to Gemfile.lock on master now conflicts with your PR) then please rebase your PR onto the latest master. This allows you to fix the conflicts, while keeping the PR a straightforward list of commits. If there are no conflicts, then there is no need to rebase anything. + +## Localization (i18n) + +> [!IMPORTANT] +> If you make a change that involves the locale files (in `config/locales`) then please only submit changes to the `en.yml` file. The other files are updated via [Translatewiki](https://translatewiki.net/wiki/Translating:OpenStreetMap) and should not be included in your pull request. + +## Copyright Attribution + +The list of attributions on the /copyright page is managed by the [OSMF Licensing Working Group (LWG)](https://wiki.osmfoundation.org/wiki/Licensing_Working_Group). -For simple commits the one line summary is often enough and the body -of the commit message can be left out. - -## Pull Requests - -If you have forked on GitHub then the best way to submit your patches is to -push your changes back to GitHub and then send a "pull request" on GitHub. - -If your pull request is small, for example one or two commits each containing -only a few lines of code, then it is easy for the maintainers to review. - -If you are creating a larger pull request, then please help the maintainers -with making the reviews as straightforward as possible: - -* The smaller the PR, the easier it is to review. In particular if a PR is too - large to review in one sitting, or if changes are requested, then the - maintainer needs to repeatedly re-read code that has already been considered. -* The commit history is important. This is a large codebase, developed over many - years by many developers. We frequently need to read the commit history (for example - using `git blame`) to figure out what is going on. So small, understandable, - and relevant commits are important for other developers looking back at your - work in future. - -If you are creating a large pull request then please: - -* Consider splitting your pull request into multiple PRs. If part of your work - can be considered standalone, or is a foundation for the rest of your work, - please submit it separately first. -* Avoid including "fixup" commits. If you have added a fixup commit (for example - to fix a rubocop warning, or because you changed your own new code) please - combine the fixup commit into the commit that introduced the problem. - `git rebase -i` is very useful for this. -* Avoid including "merge" commits. If your PR can no longer be merged cleanly - (for example, an unrelated change to Gemfile.lock on master now conflicts with - your PR) then please rebase your PR onto the latest master. This allows you to - fix the conflicts, while keeping the PR a straightforward list of commits. If - there are no conflicts, then there is no need to rebase anything. +> [!IMPORTANT] +> If you want to add another attribution, or make changes to the text of an existing attribution, please follow these steps: +> +> * First, contact the LWG to discuss your proposed changes. +> * If the LWG approves, please create a pull request with your proposed changes. +> * Finally, please ask the LWG to formally approve the wording used in the pull request (by having an LWG member comment on the PR). +> +> When we have formal confirmation from LWG, we can go ahead and merge the PR. -- 2.39.5