Add README.md As Primary Documentation File

cli/ballerina-cli/src/main/java/io/ballerina/cli/cmd/CommandUtil.java

@@ -972,9 +972,9 @@ private static void initLibPackage(Path path, String packageName) throws IOExcep
 
         write(ballerinaToml, defaultManifest.getBytes(StandardCharsets.UTF_8));
 
-        // Create Package.md
-        String packageMd = FileUtils.readFileAsString(NEW_CMD_DEFAULTS + "/Package.md");
-        write(path.resolve(ProjectConstants.PACKAGE_MD_FILE_NAME), packageMd.getBytes(StandardCharsets.UTF_8));
+        // Create README.md
+        String readmeMd = FileUtils.readFileAsString(NEW_CMD_DEFAULTS + "/" + ProjectConstants.README_MD_FILE_NAME);
+        write(path.resolve(ProjectConstants.README_MD_FILE_NAME), readmeMd.getBytes(StandardCharsets.UTF_8));
     }
 
     /**

cli/ballerina-cli/src/main/java/io/ballerina/cli/cmd/PackCommand.java

@@ -14,10 +14,14 @@
 import io.ballerina.projects.Project;
 import io.ballerina.projects.ProjectException;
 import io.ballerina.projects.directory.BuildProject;
+import io.ballerina.projects.internal.PackageDiagnostic;
+import io.ballerina.projects.internal.ProjectDiagnosticErrorCode;
 import io.ballerina.projects.util.ProjectConstants;
 import io.ballerina.projects.util.ProjectUtils;
 import io.ballerina.toml.semantic.TomlType;
 import io.ballerina.toml.semantic.ast.TomlTableNode;
+import io.ballerina.tools.diagnostics.DiagnosticInfo;
+import io.ballerina.tools.diagnostics.DiagnosticSeverity;
 import org.ballerinalang.toml.exceptions.SettingsTomlException;
 import org.wso2.ballerinalang.util.RepoUtils;
 import picocli.CommandLine;
@@ -246,6 +250,18 @@ public void execute() {
         // Check package files are modified after last build
         boolean isPackageModified = isProjectUpdated(project);
 
+        // Checks if Package.md is present and issues a warning
+        Path packageMd = project.sourceRoot().resolve(ProjectConstants.PACKAGE_MD_FILE_NAME);
+        if (packageMd.toFile().exists()) {
+            String warning = "The use of Package.md and Module.md is deprecated. " +
+                    "Update the package to add a README.md file.\n";
+            DiagnosticInfo diagnosticInfo = new DiagnosticInfo(ProjectDiagnosticErrorCode.
+                    DEPRECATED_DOC_FILE.diagnosticId(), warning, DiagnosticSeverity.WARNING);
+            PackageDiagnostic packageDiagnostic = new PackageDiagnostic(diagnosticInfo,
+                    project.currentPackage().packageName().toString());
+            this.outStream.println(packageDiagnostic);
+        }
+
         TaskExecutor taskExecutor = new TaskExecutor.TaskBuilder()
                 .addTask(new CleanTargetDirTask(isPackageModified, buildOptions.enableCache()), isSingleFileBuild)
                 .addTask(new RunBuildToolsTask(outStream), isSingleFileBuild)

cli/ballerina-cli/src/main/java/io/ballerina/cli/cmd/PushCommand.java

@@ -69,6 +69,7 @@
 import static io.ballerina.projects.util.ProjectConstants.LOCAL_TOOLS_JSON;
 import static io.ballerina.projects.util.ProjectConstants.SETTINGS_FILE_NAME;
 import static io.ballerina.projects.util.ProjectUtils.getAccessTokenOfCLI;
+import static io.ballerina.projects.util.ProjectUtils.getPackageNameFromBalaName;
 import static io.ballerina.projects.util.ProjectUtils.initializeProxy;
 import static io.ballerina.runtime.api.constants.RuntimeConstants.SYSTEM_PROP_BAL_DEBUG;
 
@@ -358,21 +359,33 @@
     }
 
     private static void validatePackageMdAndBalToml(Path balaPath) {
+        // Gets package name from balapath
+        String packageName = getPackageNameFromBalaName(balaPath.toFile().getName());
+
         try (ZipInputStream zip = new ZipInputStream(Files.newInputStream(balaPath, StandardOpenOption.READ))) {
             ZipEntry entry;
             while ((entry = zip.getNextEntry()) != null) {
+                // Checks if Package.md or README.md exists and is not empty
                 if (entry.getName().equals(
                         ProjectConstants.BALA_DOCS_DIR + "/" + ProjectConstants.PACKAGE_MD_FILE_NAME)) {
                     if (entry.getSize() == 0) {
                         throw new ProjectException(ProjectConstants.PACKAGE_MD_FILE_NAME + " cannot be empty.");
                     }
                     return;
+                } else if (entry.getName().equals(
+                        ProjectConstants.BALA_DOCS_DIR + "/" + ProjectConstants.MODULES_ROOT + "/"
+                                + packageName + "/" + ProjectConstants.README_MD_FILE_NAME)) {
+                    if (entry.getSize() == 0) {
+                        throw new ProjectException(ProjectConstants.README_MD_FILE_NAME + " cannot be empty.");
+                    }
+                    return;
                 }
             }
         } catch (IOException e) {
             throw new ProjectException("error while validating the bala file: " + e.getMessage(), e);
         }
-        throw new ProjectException(ProjectConstants.PACKAGE_MD_FILE_NAME + " is missing in bala file:" + balaPath);
+        // Throws an exception if both files aren't present
+        throw new ProjectException(ProjectConstants.README_MD_FILE_NAME + " is missing in bala file:" + balaPath);
     }
 
     private void pushBalaToCustomRepo(Path balaFilePath) {

cli/ballerina-cli/src/main/resources/new_cmd_defaults/README.md

@@ -0,0 +1,5 @@
+Prints "Hello, World!" with a main function.
+
+# Overview
+Provides an overview about the package when generating the API documentations.
+For example, refer to https://lib.ballerina.io/ballerina/io/latest

cli/ballerina-cli/src/test/java/io/ballerina/cli/cmd/NewCommandTest.java

@@ -554,13 +554,13 @@ public void testNewCommandWithLib(String packagePath) throws IOException {
 
         String packageName = Paths.get(args[0]).getFileName().toString();
         String expectedTomlContent = "[package]\n" +
-                "org = \"" + System.getProperty("user.name").replaceAll("[^a-zA-Z0-9_]", "_") + "\"\n" +
+                "org = \"" + System.getProperty("user.name").toLowerCase().replaceAll("[^a-z0-9_]", "_") + "\"\n" +
                 "name = \"" + packageName + "\"\n" +
                 "version = \"0.1.0\"\n" +
                 "distribution = \"" + RepoUtils.getBallerinaShortVersion() + "\"" +
                 "\n";
         Assert.assertTrue(tomlContent.contains(expectedTomlContent));
-        Assert.assertTrue(Files.exists(packageDir.resolve(ProjectConstants.PACKAGE_MD_FILE_NAME)));
+        Assert.assertTrue(Files.exists(packageDir.resolve(ProjectConstants.README_MD_FILE_NAME)));
         Assert.assertTrue(Files.exists(packageDir.resolve(packageName + ".bal")));
         Assert.assertTrue(Files.exists(packageDir.resolve(ProjectConstants.TEST_DIR_NAME)));
         Assert.assertTrue(Files.exists(packageDir.resolve(ProjectConstants.RESOURCE_DIR_NAME)));

cli/ballerina-cli/src/test/java/io/ballerina/cli/cmd/PushCommandTest.java

@@ -372,7 +372,7 @@ public void testPushWithoutPackageMd() throws IOException {
                 projectPath.resolve("target").resolve("bala").resolve("foo-winery-any-0.1.0.bala").toFile().exists());
 
         // Push
-        String expected = "Package.md is missing in bala file";
+        String expected = "README.md is missing in bala file";
 
         PushCommand pushCommand = new PushCommand(projectPath, printStream, printStream, false);
         new CommandLine(pushCommand).parse();

cli/ballerina-cli/src/test/resources/test-resources/command-outputs/unix/pack-central-tool.txt

@@ -1,3 +1,5 @@
+WARNING [sample_tool_template] The use of Package.md and Module.md is deprecated. Update the package to add a README.md file.
+
 Compiling source
 	testorg/sample_tool_template:1.0.0
 

cli/ballerina-cli/src/test/resources/test-resources/command-outputs/windows/pack-central-tool.txt

@@ -1,5 +1,7 @@
-Compiling source
-	testorg/sample_tool_template:1.0.0
-
-Creating bala
-	target\bala\testorg-sample_tool_template-java17-1.0.0.bala
+WARNING [sample_tool_template] The use of Package.md and Module.md is deprecated. Update the package to add a README.md file.
+
+Compiling source
+	testorg/sample_tool_template:1.0.0
+
+Creating bala
+	target\bala\testorg-sample_tool_template-java17-1.0.0.bala

compiler/ballerina-lang/src/main/java/io/ballerina/projects/BalaWriter.java

@@ -98,9 +98,9 @@ protected BalaWriter() {
      */
     public Path write(Path balaPath) {
         String balaName = getBalaName(this.packageContext.packageOrg().value(),
-                                      this.packageContext.packageName().value(),
-                                      this.packageContext.packageVersion().value().toString(),
-                                      this.target);
+                this.packageContext.packageName().value(),
+                this.packageContext.packageVersion().value().toString(),
+                this.target);
         // Create the archive over write if exists
         try (ZipOutputStream balaOutputStream = new ZipOutputStream(
                 new FileOutputStream(String.valueOf(balaPath.resolve(balaName))))) {
@@ -125,8 +125,8 @@ private void populateBalaArchive(ZipOutputStream balaOutputStream)
 
         addBalaJson(balaOutputStream);
         addPackageDoc(balaOutputStream,
-                      this.packageContext.project().sourceRoot(),
-                      this.packageContext.packageName().toString());
+                this.packageContext.project().sourceRoot(),
+                this.packageContext.packageName().toString());
         addPackageSource(balaOutputStream);
         addIncludes(balaOutputStream);
         Optional<JsonArray> platformLibs = addPlatformLibs(balaOutputStream);
@@ -150,8 +150,8 @@ private void addBalaJson(ZipOutputStream balaOutputStream) {
 
     private void addPackageJson(ZipOutputStream balaOutputStream, Optional<JsonArray> platformLibs) {
         PackageJson packageJson = new PackageJson(this.packageContext.packageOrg().toString(),
-                                                  this.packageContext.packageName().toString(),
-                                                  this.packageContext.packageVersion().toString());
+                this.packageContext.packageName().toString(),
+                this.packageContext.packageVersion().toString());
 
         PackageManifest packageManifest = this.packageContext.packageManifest();
         packageJson.setLicenses(packageManifest.license());
@@ -220,7 +220,7 @@ private void setGraalVMCompatibilityProperty(PackageJson packageJson, PackageMan
     }
 
     private String otherPlatformGraalvmCompatibleVerified(String target,
-                                                                 Map<String, PackageManifest.Platform> platforms) {
+                                                          Map<String, PackageManifest.Platform> platforms) {
         for (Map.Entry<String, PackageManifest.Platform> platform : platforms.entrySet()) {
             if (!platform.getKey().equals(target) && platform.getValue().graalvmCompatible() != null) {
                 return platform.getKey();
@@ -245,51 +245,66 @@ private void addPackageDoc(ZipOutputStream balaOutputStream, Path packageSourceD
             throws IOException {
         final String packageMdFileName = "Package.md";
         final String moduleMdFileName = "Module.md";
+        final String readmeMdFileName = "README.md";
 
-        Path packageMd = packageSourceDir.resolve(packageMdFileName);
         Path docsDirInBala = Paths.get(BALA_DOCS_DIR);
-
-        // If `Package.md` exists, create the docs directory & add `Package.md`
-        if (packageMd.toFile().exists()) {
-            Path packageMdInBala = docsDirInBala.resolve(packageMdFileName);
-            putZipEntry(balaOutputStream, packageMdInBala,
-                    new FileInputStream(String.valueOf(packageMd)));
-        }
+        Path packageMd = packageSourceDir.resolve(packageMdFileName);
 
         // If `icon` mentioned in the Ballerina.toml, add it to docs directory
         String icon = this.packageContext.packageManifest().icon();
         if (icon != null && !icon.isEmpty()) {
             Path iconPath = getIconPath(icon);
             Path iconInBala = docsDirInBala.resolve(iconPath.getFileName());
-            putZipEntry(balaOutputStream, iconInBala, new FileInputStream(String.valueOf(iconPath)));
+            try (FileInputStream inputStream = new FileInputStream(String.valueOf(iconPath))) {
+                putZipEntry(balaOutputStream, iconInBala, inputStream);
+            }
         }
 
-        // If `Module.md` of default module exists, create `docs/modules` directory & add `Module.md`
-        Path defaultModuleMd = packageSourceDir.resolve(moduleMdFileName);
-        Path modulesDirInBalaDocs = docsDirInBala.resolve(MODULES_ROOT);
+        // If Package.md and Module.md does not exist, pack README.md
+        if (!packageMd.toFile().exists()) {
+            packModulesToBala(pkgName, readmeMdFileName, balaOutputStream, packageSourceDir);
+        } else {
+            // Creates the docs directory & add `Package.md`
+            Path packageMdInBala = docsDirInBala.resolve(packageMdFileName);
+            try (FileInputStream inputStream = new FileInputStream(String.valueOf(packageMd))) {
+                putZipEntry(balaOutputStream, packageMdInBala, inputStream);
+            }
 
-        if (defaultModuleMd.toFile().exists()) {
-            Path defaultModuleMdInBalaDocs = modulesDirInBalaDocs.resolve(pkgName).resolve(moduleMdFileName);
-            putZipEntry(balaOutputStream, defaultModuleMdInBalaDocs,
-                    new FileInputStream(String.valueOf(defaultModuleMd)));
+            // Packs the module.md of default and non-default modules
+            packModulesToBala(pkgName, moduleMdFileName, balaOutputStream, packageSourceDir);
         }
+    }
+
+    private void packModulesToBala(String pkgName, String fileName, ZipOutputStream balaOutputStream,
+                                   Path packageSourceDir)
+            throws IOException {
 
-        // Add other module docs
+        Path defaultMd = packageSourceDir.resolve(fileName);
         File modulesSourceDir = new File(String.valueOf(packageSourceDir.resolve(MODULES_ROOT)));
-        File[] directoryListing = modulesSourceDir.listFiles();
+        Path modulesDirInBalaDocs = Paths.get(BALA_DOCS_DIR).resolve(MODULES_ROOT);
 
+        // Packs default Module
+        if (defaultMd.toFile().exists()) {
+            Path defaultMdInBala = modulesDirInBalaDocs.resolve(pkgName).resolve(fileName);
+            try (FileInputStream inputStream = new FileInputStream(String.valueOf(defaultMd))) {
+                putZipEntry(balaOutputStream, defaultMdInBala, inputStream);
+            }
+        }
+        // Packs non-default modules
+        File[] directoryListing = modulesSourceDir.listFiles();
         if (directoryListing != null) {
             for (File moduleDir : directoryListing) {
                 if (moduleDir.isDirectory()) {
-                    // Get `Module.md` path
-                    Path otherModuleMd = packageSourceDir.resolve(MODULES_ROOT).resolve(moduleDir.getName())
-                            .resolve(moduleMdFileName);
-                    // Create `package.module` folder, if `Module.md` path exists
-                    if (otherModuleMd.toFile().exists()) {
-                        Path otherModuleMdInBalaDocs = modulesDirInBalaDocs.resolve(pkgName + "." + moduleDir.getName())
-                                .resolve(moduleMdFileName);
-                        putZipEntry(balaOutputStream, otherModuleMdInBalaDocs,
-                                new FileInputStream(String.valueOf(otherModuleMd)));
+                    // Gets filename path
+                    Path nonDefaultModuleMd = packageSourceDir.resolve(MODULES_ROOT).resolve(moduleDir.getName())
+                            .resolve(fileName);
+                    // Creates `package.module` folder, if filename path exists
+                    if (nonDefaultModuleMd.toFile().exists()) {
+                        Path nonDefaultModuleMdInBalaDocs = modulesDirInBalaDocs
+                                .resolve(pkgName + "." + moduleDir.getName()).resolve(fileName);
+                        try (FileInputStream inputStream = new FileInputStream(String.valueOf(nonDefaultModuleMd))) {
+                            putZipEntry(balaOutputStream, nonDefaultModuleMdInBalaDocs, inputStream);
+                        }
                     }
                 }
             }
@@ -331,7 +346,7 @@ private void addPackageSource(ZipOutputStream balaOutputStream) throws IOExcepti
                     char[] documentContent = document.textDocument().toCharArray();
 
                     putZipEntry(balaOutputStream, documentPath,
-                                new ByteArrayInputStream(new String(documentContent).getBytes(StandardCharsets.UTF_8)));
+                            new ByteArrayInputStream(new String(documentContent).getBytes(StandardCharsets.UTF_8)));
                 }
             }
         }
@@ -374,7 +389,7 @@ private void addDependenciesJson(ZipOutputStream balaOutputStream) {
 
         try {
             putZipEntry(balaOutputStream, Paths.get(DEPENDENCY_GRAPH_JSON),
-                        new ByteArrayInputStream(gson.toJson(depGraphJson).getBytes(Charset.defaultCharset())));
+                    new ByteArrayInputStream(gson.toJson(depGraphJson).getBytes(Charset.defaultCharset())));
         } catch (IOException e) {
             throw new ProjectException("Failed to write '" + DEPENDENCY_GRAPH_JSON + "' file: " + e.getMessage(), e);
         }

compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/ProjectDiagnosticErrorCode.java

@@ -61,6 +61,9 @@ public enum ProjectDiagnosticErrorCode implements DiagnosticCode {
     // Error codes used for Jar resolving.
     CONFLICTING_PLATFORM_JAR_FILES("BCE5501", "conflicting.platform.jars.type"),
     PROVIDED_PLATFORM_JAR_IN_EXECUTABLE("BCE5502", "provided.platform.jars"),
+
+    // Error codes used for pack command
+    DEPRECATED_DOC_FILE("BCE5601", "deprecated.doc.file"),
     ;
 
     private final String diagnosticId;

compiler/ballerina-lang/src/main/java/io/ballerina/projects/util/ProjectConstants.java

@@ -44,6 +44,7 @@ private ProjectConstants() {}
     public static final String DEVCONTAINER = ".devcontainer.json";
     public static final String MODULE_MD_FILE_NAME = "Module.md";
     public static final String PACKAGE_MD_FILE_NAME = "Package.md";
+    public static final String README_MD_FILE_NAME = "README.md";
     public static final String PACKAGE_JSON = "package.json";
     public static final String BALA_JSON = "bala.json";
     public static final String COMPILER_PLUGIN_JSON = "compiler-plugin.json";