Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Implement Docfile #4256

Merged
merged 8 commits into from
Apr 22, 2019
Merged

Implement Docfile #4256

merged 8 commits into from
Apr 22, 2019

Conversation

dshevtsov
Copy link
Collaborator

@dshevtsov dshevtsov commented Apr 15, 2019

Purpose of this PR

This PR:

  • Adds Docfile that contatins configuration for devdocs content management
  • Updates the rake init task to use the Docfile on CICD and locally

Additional information

Internal ticket: MAGEDOC-3692

Add Docfile that contatins configuration for devdocs content management
Implement rake automation to use the Docfile locally and on CICD
@dshevtsov dshevtsov added the Site Improvements Updates to tools, processes, and site architecture that improve reader and contributor experience label Apr 15, 2019
@dshevtsov dshevtsov self-assigned this Apr 15, 2019
@jcalcaben
Copy link
Contributor

Why is the configuration file not using something standard like YAML or JSON?

@dshevtsov
Copy link
Collaborator Author

The natural language format is more user-friendly for writers. No need to delve into implementation to configure the website and no obsolete documentation in comments (comparing with _config.yml, for example).
PS And standards are boring 😁

Add a blank line at the end of file
@jeff-matthews
Copy link
Contributor

This is a really interesting and clever proposal @dshevtsov! It certainly puts a "writerly" spin on configuration, haha! However, I have reservations about creating an unconventional configuration pattern when all other site configuration uses YAML.

It creates another layer of complexity that requires unique handling in our automation scripting, which using a more standard format like YAML presumably does not.

It may also insult some writers who may misinterpret the solution as a lack of confidence in their ability to work with a more conventional format. I'm not saying that it's your intention, but it could be interpreted that way.

Perhaps if you articulated the benefits of this format over a more conventional format, it would be easier to have a constructive conversation about the pros and cons.

@belbiy
Copy link
Contributor

belbiy commented Apr 16, 2019

What if we generate this verbose explanation of the readme file? So configuration will be in YAML, but the output of the config will be explained in the plain english?

@jcalcaben
Copy link
Contributor

I'm still not sure what problem this new format addresses. JSON and YAML are already declarative language formats with robust parsing libraries that are available in multiple programming languages.

This approach limits reusability and forces us to re-implement the parsing logic if we ever decide to move away from ruby.

If readability is the issue, I argue that the following is just as easy to read and understand in the context of a configuration file:

{
    "repositoryDependencies": [
        {
            "githubUrl": "magento/magento2-functional-testing-framework",
            "branch": "develop",
            "sourceDirectory": "docs",
            "targetDirectory": "mftf",
        },
        {
            "githubUrl": "magento/devdocs-m1",
            "branch": "master",
            "targetDirectory": "m1x",
        }
    ]
}

@jeff-matthews
Copy link
Contributor

I agree with James, but I prefer YAML over JSON. JSON is more error prone when it comes to manual editing in my opinion.

@dshevtsov
Copy link
Collaborator Author

It doesn't address some specific problem. It just shows another way of a configuration file use. The file is very simple, so why do we use YAML and JSON when we can use English. No need to use other libraries, only regular expressions functionality that is very probably be the same in different languages.
If the website will move to other static generator, most of the infrastructure and configuration will need to be re-implemented I think,; and having a simple text file that describes the external content dependencies configuration would help, because any other other format will still require some documentation to explain what is this file about and what the parameters are set for.

@jeff-matthews
Copy link
Contributor

I worry that the natural language syntax may become unwieldily over time if we need to extend the Docfile or make it more complex.

@dshevtsov
Copy link
Collaborator Author

The format can be changed when the configuration will become complex enough.
I understand concerns about maintenance, but I don't see in this case much more complexity than maintaining any other format.

I'm changing the format to YAML, will update it in this PR.

@dshevtsov
Copy link
Collaborator Author

Changed Docfile to Docfile.yml.

Copy link
Contributor

@jeff-matthews jeff-matthews left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @dshevtsov. I tested this branch locally and it works well. It's definitely an improvement over hardcoding all the shell script options in the rake init task.

Before approving this PR, I'd like to try something different since this impacts our Jenkins pipelines as well. We need to start creating changes to pipeline scripts in git. I know that can be inconvenient since we often need to test changes directly in the Jenkins console before we know precisely which changes we need to make or which changes will work. However, I think it's something we need to start getting used to.

Please create a PR for all impacted Jenkins pipelines and link to this PR.

It doesn't look like our new multirepo-build-deploy-staging pipeline has been added to the infrastructure repo yet. I'll add it so you can create a PR.

@dshevtsov
Copy link
Collaborator Author

running tests

@dshevtsov
Copy link
Collaborator Author

running tests

@dshevtsov dshevtsov merged commit 5e2dfc3 into master Apr 22, 2019
@ghost
Copy link

ghost commented Apr 22, 2019

Hi @dshevtsov, thank you for your contribution!
Please, complete Contribution Survey, it will take less than a minute.
Your feedback will help us to improve contribution process.

@dshevtsov dshevtsov deleted the ds_MAGEDOC-3692_docfile branch April 22, 2019 19:23
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Site Improvements Updates to tools, processes, and site architecture that improve reader and contributor experience
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants