diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/doc_styleguide.md | 52 | ||||
| -rw-r--r-- | doc/development/instrumentation.md | 15 | ||||
| -rw-r--r-- | doc/development/migration_style_guide.md | 16 |
3 files changed, 69 insertions, 14 deletions
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 8292b393757..f5d97179f8a 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -103,14 +103,14 @@ Inside the document: - Every piece of documentation that comes with a new feature should declare the GitLab version that feature got introduced. Right below the heading add a - note: `_**Note:** This feature was introduced in GitLab 8.3_` + note: `>**Note:** This feature was introduced in GitLab 8.3` - If possible every feature should have a link to the MR that introduced it. The above note would be then transformed to: - `_**Note:** This feature was [introduced][ce-1242] in GitLab 8.3_`, where + `>**Note:** This feature was [introduced][ce-1242] in GitLab 8.3`, where the [link identifier](#links) is named after the repository (CE) and the MR number - If the feature is only in GitLab EE, don't forget to mention it, like: - `_**Note:** This feature was introduced in GitLab EE 8.3_`. Otherwise, leave + `>**Note:** This feature was introduced in GitLab EE 8.3`. Otherwise, leave this mention out ## References @@ -141,6 +141,48 @@ Inside the document: [ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Ruby download website" +## Changing document location + +Changing a document's location is not to be taken lightly. Remember that the +documentation is available to all installations under `help/` and not only to +GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the +Documentation team beforehand. + +If you indeed need to change a document's location, do NOT remove the old +document, but rather put a text in it that points to the new location, like: + +``` +This document was moved to [path/to/new_doc.md](path/to/new_doc.md). +``` + +where `path/to/new_doc.md` is the relative path to the root directory `doc/`. + +--- + +For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to +`doc/administration/lfs.md`, then the steps would be: + +1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md` +1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with: + + ``` + This document was moved to [administration/lfs.md](../../administration/lfs.md). + ``` + +1. Find and replace any occurrences of the old location with the new one. + A quick way to find them is to use `grep`: + + ``` + grep -nR "lfs_administration.md" doc/ + ``` + + The above command will search in the `doc/` directory for + `lfs_administration.md` recursively and will print the file and the line + where this file is mentioned. Note that we used just the filename + (`lfs_administration.md`) and not the whole the relative path + (`workflow/lfs/lfs_administration.md`). + + ## API Here is a list of must-have items. Use them in the exact order that appears @@ -222,8 +264,8 @@ curl --data "name=foo" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab. #### Post data using JSON content -_**Note:** In this example we create a new group. Watch carefully the single -and double quotes._ +> **Note:** In this example we create a new group. Watch carefully the single +and double quotes. ```bash curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v3/groups diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 9168c70945a..6cd9b274d11 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -15,8 +15,8 @@ instrument code: * `instrument_instance_method`: instruments a single instance method. * `instrument_class_hierarchy`: given a Class this method will recursively instrument all sub-classes (both class and instance methods). -* `instrument_methods`: instruments all public class methods of a Module. -* `instrument_instance_methods`: instruments all public instance methods of a +* `instrument_methods`: instruments all public and private class methods of a Module. +* `instrument_instance_methods`: instruments all public and private instance methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` @@ -97,15 +97,16 @@ def #{name}(#{args_signature}) trans = Gitlab::Metrics::Instrumentation.transaction if trans - start = Time.now - retval = super - duration = (Time.now - start) * 1000.0 + start = Time.now + cpu_start = Gitlab::Metrics::System.cpu_time + retval = super + duration = (Time.now - start) * 1000.0 if duration >= Gitlab::Metrics.method_call_threshold - trans.increment(:method_duration, duration) + cpu_duration = Gitlab::Metrics::System.cpu_time - cpu_start trans.add_metric(Gitlab::Metrics::Instrumentation::SERIES, - { duration: duration }, + { duration: duration, cpu_duration: cpu_duration }, method: #{label.inspect}) end diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 02e024ca15a..8a7547e5322 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -34,6 +34,15 @@ First, you need to provide information on whether the migration can be applied: 3. online with errors on new instances while migrating 4. offline (needs to happen without app servers to prevent db corruption) +For example: + +``` +# rubocop:disable all +# Migration type: online without errors (works on previous version and new one) +class MyMigration < ActiveRecord::Migration +... +``` + It is always preferable to have a migration run online. If you expect the migration to take particularly long (for instance, if it loops through all notes), this is valuable information to add. @@ -48,7 +57,6 @@ be possible to downgrade in case of a vulnerability or bugs. In your migration, add a comment describing how the reversibility of the migration was tested. - ## Removing indices If you need to remove index, please add a condition like in following example: @@ -70,6 +78,7 @@ so: ``` class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers disable_ddl_transaction! def change @@ -90,8 +99,11 @@ value of `10` you'd write the following: ``` class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + disable_ddl_transaction! + def up - add_column_with_default(:projects, :foo, :integer, 10) + add_column_with_default(:projects, :foo, :integer, default: 10) end def down |