tyk-docs icon indicating copy to clipboard operation
tyk-docs copied to clipboard

[DX-1343] Replace master/slave content where possible, for tier 1 compliance with inclusive naming

Open dcs3spp opened this issue 9 months ago • 5 comments

User description

For internal users - Please add a Jira DX PR ticket to the subject!

DX-1343


Preview Link


Description

Within the docs content there are occurrences of master/slave. This ticket involves updating the content where possible. Due to 3rd party dependencies and configuration parameters in Tyk components, it will not be possible to update some content until the product has been updated.

Screenshots (if appropriate)


Checklist

  • [ ] I have added a preview link to the PR description.
  • [x] I have reviewed the guidelines for contributing to this repository.
  • [x] I have read the technical guidelines for contributing to this repository.
  • [x] Make sure you have started your change off our latest master.
  • [x] I labelled the PR

PR Type

Enhancement, Documentation


Description

  • Updated terminology from 'master/slave' to 'primary/replica' and 'workers' across multiple documentation pages to align with inclusive language guidelines.
  • Minor formatting adjustment in TCP proxy documentation without altering the content.

Changes walkthrough 📝

Relevant files
Enhancement
concepts.md
Update Terminology in Mutual TLS Concepts                               

tyk-docs/content/basic-config-and-security/security/mutual-tls/concepts.md

  • Updated terminology from 'slaves' to 'workers' in the context of MDCB
    environment.
  • +3/-3     
    uptime-tests.md
    Update Master to Primary in Uptime Tests                                 

    tyk-docs/content/planning-for-production/ensure-high-availability/uptime-tests.md

  • Changed 'master' to 'primary' in the context of uptime tests
    configuration.
  • +3/-3     
    redis.md
    Update Redis Terminology for Clarity                                         

    tyk-docs/content/planning-for-production/redis.md

    • Updated 'master Redis instance' to 'primary Redis instance'.
    +1/-1     
    on-aws.md
    Update MongoDB HA Terminology in AWS Installation Guide   

    tyk-docs/content/tyk-on-premises/installation/on-aws.md

  • Updated MongoDB HA terminology from 'Master, Slave' to 'Primary,
    Secondary'.
  • +1/-1     
    redis-cluster.md
    Update Redis Cluster Configuration Terminology                     

    tyk-docs/content/tyk-stack/tyk-gateway/configuration/redis-cluster.md

  • Updated Redis terminology from 'master/slave' to 'primary/replica'.
  • +3/-3     
    Formatting
    tcp-proxy.md
    Minor Formatting Adjustment in TCP Proxy                                 

    tyk-docs/content/key-concepts/tcp-proxy.md

    • Minor formatting change without content alteration.
    +1/-1     

    💡 PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

    dcs3spp avatar May 16 '24 14:05 dcs3spp

    PS. Pls add /docs/nightly to the end of url

    Name Link
    Latest commit 4081352fce06b011f10e5d4fa7702264c23f55db
    Latest deploy log https://app.netlify.com/sites/tyk-docs/deploys/6646174f02ce1f000897831a
    Deploy Preview https://deploy-preview-4641--tyk-docs.netlify.app
    Preview on mobile
    Toggle QR Code...

    QR Code

    Use your smartphone camera to open QR code link.

    To edit notification comments on pull requests, go to your Netlify site configuration.

    netlify[bot] avatar May 16 '24 14:05 netlify[bot]

    PS. Pls add /docs/nightly to the end of url

    Name Link
    Latest commit 9de5495586500aa4fc9c6df88637430b40c95580
    Latest deploy log https://app.netlify.com/sites/tyk-docs/deploys/6650aa5577dfe30008bc8522
    Deploy Preview https://deploy-preview-4641--tyk-docs.netlify.app
    Preview on mobile
    Toggle QR Code...

    QR Code

    Use your smartphone camera to open QR code link.

    To edit notification comments on pull requests, go to your Netlify site configuration.

    netlify[bot] avatar May 16 '24 14:05 netlify[bot]

    PR Description updated to latest commit (https://github.com/TykTechnologies/tyk-docs/commit/b5195f62a44de4b29943aa416bc62178f7caf5d7)

    github-actions[bot] avatar May 16 '24 15:05 github-actions[bot]

    PR Review 🔍

    ⏱️ Estimated effort to review [1-5]

    2, because the changes are straightforward and mainly involve terminology updates from non-inclusive to inclusive language. The PR is well-documented and the changes are clearly described, making it easier to review.

    🧪 Relevant tests

    No

    ⚡ Possible issues

    No

    🔒 Security concerns

    No

    Code feedback:
    relevant filetyk-docs/content/key-concepts/tcp-proxy.md
    suggestion      

    The sentence still mentions "Redis master" which should be updated to "Redis primary" for consistency with the inclusive language initiative. [important]

    relevant lineHere is quite a complex example of using health checks, which shows a Redis Sentinel setup. In this configuration, we put a TCP proxy, e.g. Tyk, on top of two or more Redis nodes, and the role of the proxy will always direct the user to Redis master.

    github-actions[bot] avatar May 16 '24 15:05 github-actions[bot]

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Security
    Add a security note about sharing secrets across environments

    Consider adding a note or warning about the security implications of sharing the
    security.private_certificate_encoding_secret across different environments. This could
    help users understand the potential risks and encourage them to manage their secrets more
    securely.

    tyk-docs/content/basic-config-and-security/security/mutual-tls/concepts.md [88-89]

     To solve this issue, you need to set `security.private_certificate_encoding_secret`  in the MDCB configuration file to the same value as specified in your management Gateway configuration file. By knowing the original secret, MDCB will be able to decode private keys, and 
    -send them to client without password.
    +send them to client without password. **Note:** Sharing secrets across different environments can lead to security risks. It is advisable to manage your secrets securely and consider the implications of such configurations.
     
    
    Suggestion importance[1-10]: 7

    Why: The suggestion to add a security note is relevant and enhances the documentation by highlighting potential security risks. It directly relates to the new code added about sharing secrets.

    7
    Enhancement
    Clarify the primary node election process in uptime tests

    Clarify the election process for the primary node in uptime tests to enhance
    understanding. Adding details about the election mechanism can help users better grasp how
    Tyk handles primary node elections.

    tyk-docs/content/planning-for-production/ensure-high-availability/uptime-tests.md [24]

    -When uptime tests are added into a Tyk cluster, a single node will elect itself as primary.
    +When uptime tests are added into a Tyk cluster, a single node will elect itself as primary based on a predefined set of criteria such as node availability, response time, or custom user-defined metrics.
     
    
    Suggestion importance[1-10]: 6

    Why: The suggestion to clarify the election process is valid and improves understanding. However, it does not address any critical functionality or security issue, hence the moderate score.

    6
    Explain the roles of primary and replica instances in a Redis cluster

    Add a brief explanation about the role of primary and replica instances in a Redis cluster
    to provide readers with a better understanding of their functions and importance.

    tyk-docs/content/tyk-stack/tyk-gateway/configuration/redis-cluster.md [127]

    -It is important that Tyk can connect to all primary and replica instances.
    +It is important that Tyk can connect to all primary and replica instances. In a Redis cluster, primary instances handle write operations while replicas are responsible for handling read operations and providing redundancy for failover.
     
    
    Suggestion importance[1-10]: 6

    Why: The suggestion to explain the roles of primary and replica instances is useful for reader comprehension. It's a good enhancement but not critical to the functionality or security of the system.

    6

    github-actions[bot] avatar May 16 '24 15:05 github-actions[bot]

    Thanks for reviewing and giving feedback on this @andyo-tyk

    I have committed your suggestions. Should I use deployments instead of environments for the MDCB content?

    dcs3spp avatar May 17 '24 10:05 dcs3spp

    @caroltyk Are you ok with the suggestions made in https://deploy-preview-4641--tyk-docs.netlify.app/docs/nightly/basic-config-and-security/security/mutual-tls/concepts

    @andyo-tyk Thanks, I have committed suggestions with suggested changes for review

    dcs3spp avatar May 20 '24 11:05 dcs3spp

    /release to release-5.3

    dcs3spp avatar May 24 '24 16:05 dcs3spp

    Working on it! Note that it can take a few minutes.

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    @dcs3spp Succesfully merged PR

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    /release to release-5.2

    dcs3spp avatar May 24 '24 16:05 dcs3spp

    Working on it! Note that it can take a few minutes.

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    @dcs3spp Succesfully merged PR

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    /release to release-5.1

    dcs3spp avatar May 24 '24 16:05 dcs3spp

    Working on it! Note that it can take a few minutes.

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    @dcs3spp Succesfully merged PR

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    /release to release-5

    dcs3spp avatar May 24 '24 16:05 dcs3spp

    Working on it! Note that it can take a few minutes.

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]

    @dcs3spp Succesfully merged PR

    tykbot[bot] avatar May 24 '24 16:05 tykbot[bot]