From e6f563f9b2e4e7c782ba0aab6dfba7de91c7aa25 Mon Sep 17 00:00:00 2001
From: Deepak Khatri <deepaklorkhatri7@gmail.com>
Date: Wed, 31 Jan 2024 16:08:19 +0530
Subject: [PATCH] Resolve !5 comments
---
contrib/index.rst | 70 +++++++++++++++++++++++++++++++++++++----------
ideas/index.rst | 7 +++--
2 files changed, 60 insertions(+), 17 deletions(-)
diff --git a/contrib/index.rst b/contrib/index.rst
index f70292f..023f7cb 100644
--- a/contrib/index.rst
+++ b/contrib/index.rst
@@ -41,21 +41,45 @@ After successfully forking the project you have to,
After selecting the file you have to click on ``edit button`` and then choose either of the options from drop-down,
-1. Open in Web IDE, choose this if you want to work on multiple files.
-2. Edit single file, choose this if you want to make some small edits in a single file.
+1. ``Open in Web IDE``, choose this if you want to work on multiple files.
+2. ``Edit single file``, choose this if you want to make some small edits in a single file.
-.. note:: Choosing Web IDE will load a full VS Code IDE from server which can be bit heavy sometimes.
+.. image:: media/edit-button.png
+ :align: center
+
+.. note::
+ Choosing Web IDE will load a `Visual Studio Code Server <https://code.visualstudio.com/docs/remote/vscode-server>`_
+ instance which is a feature rich source code editor. Depending on the internent connection your machine will take some to
+ load the editor and it can be a bit heavy for some machines to handle. Once fully loaded it should run smoothly but, if that is
+ not the case then please consider using single file editor option. Considering majority of the users will be using Web IDE option,
+ we are using the Web IDE for the rest of this guide.
Start editing
*************
-If you select to open your file in web IDE you'll see a familar interface. The IDE is actually a VS code server hosted on OpenBeagle.
+If you select to open your file in web IDE you'll see a familar interface. The GitLab web IDE is actually a rich
+`Visual Studio Code Server <https://code.visualstudio.com/docs/remote/vscode-server>`_ hosted on OpenBeagle.
.. image:: media/ide.png
:align: center
-.. tip:: If you are new to RST you can checkout our `RST cheatsheet <https://docs.beagleboard.org/latest/intro/contribution/rst-cheat-sheet.html>`_
- to get yourself familiar with RST.
+.. tip:: We use `reStructuredText (RST) <https://en.wikipedia.org/wiki/ReStructuredText>`_ for all of our documentation projects
+ including `this GSoC site <https://gsoc.beagleboard.io/>`_ and `main docs site <https://docs.beagleboard.org/latest/>`_.
+ If you are new to reStructuredText you can checkout our `reStructuredText cheatsheet <https://docs.beagleboard.org/latest/
+ intro/contribution/rst-cheat-sheet.html>`_ to get yourself familiar with reStructuredText.
+
+.. admonition:: Why not use Markdown for documentation?
+
+ Because reStructuredText stands out against Markdown as,
+
+ 1. It’s more fully-featured.
+ 2. It’s much more standardized and uniform.
+ 3. It has built-in support for extensions.
+
+ For more detailed comparison you can checkout `this article on reStructuredText vs. Markdown for technical
+ documentation <https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/>`_
+
+
Now you have to select a file and start editing. Below image shows some,
@@ -65,8 +89,8 @@ Now you have to select a file and start editing. Below image shows some,
.. image:: media/make-edits.png
:align: center
-Just like you do on your normal VS Code IDE, to commit your changes you can either click on Source
-control button on press ``CTRL + SHIFT + G`` to see all the edited fils.
+Just like you do on your normal Visual Studio Code desktop application, to commit your changes you can either click on Source
+control ( :fa:`code-branch;pst-color-secondary` ) button or press ``CTRL + SHIFT + G`` to see all the edited fils.
.. image:: media/make-edits.png
:align: center
@@ -79,26 +103,39 @@ After swithing to source control you have to,
.. image:: media/commit-changes.png
:align: center
-After clicking to commit button you'll be prompted with this window, where you can choose to
-commit to main if it's a single edit or commit to a new branch if you want to keep your main branch clean.
+After clicking ``Commit to 'main'`` button you'll be prompted with a window (shown below) with three options,
+
+1. ``Create new branch``
+2. ``Cancel``
+3. ``Continue``
+
+Click on ``Continue`` button if you want to commit to main (default branch) if it's a single edit or commit.
+Click on ``Create new branch`` if you want to create a new branch and want to keep your main branch clean. Advantage
+of creating a new branch is that assigned reviewer for a pull request / merge request can also add commits to your
+newly created branch which is not possible for your main branch because it's a `protected branch <https://docs.gitlab.com/
+ee/user/project/protected_branches.html>`_ by default.
.. image:: media/commit-branch.png
:align: center
-When all done right, the lower right side of the IDE you'll a prompt showing sucess message.
+When all done right, the lower right side of the ``Web IDE`` you'll a prompt showing ``Success! Your changes have been committed`` message with
+two button,
+
+1. ``Got to Project``
+2. ``Continue working``
.. image:: media/commit-success.png
:align: center
-If you go back to project, you'll see the commit successfully applied and the
-green tick shows that the CI build was aldo successfull .
+If you click on ``Go to Project`` button, you'll see the commit successfully applied and the
+green tick shows that the CI build was also successful.
.. image:: media/commit.png
:align: center
-Congratulations, you have made a valuable contribution to an OpenBeagle project!
+**Congratulations!! you have made a valuable contribution to an OpenBeagle project!**
-Create Pull Request
+Create a Pull Request
**********************
After making your changes and commiting them to your forked repo, you are set to create a new Pull Request / Merge Request
@@ -112,6 +149,9 @@ merge request and fill out all the details. The image below shows all the feilds
5. If you want your commits to be shows as a single commit then you can choose the ``sqash commits ...`` check box.
6. Check if all your commits are shown in the bottom of the screen and if everything looks okay then click on ``Create merge request`` button.
+.. tip:: If you are still working on some updates, you may also choose ``Mark as draft`` checkbox (below title)
+ which indicates that you are seeking feedback before making your commits suitable to merge.
+
.. image:: media/merge-request.png
:align: center
diff --git a/ideas/index.rst b/ideas/index.rst
index 3a0f379..b7b9399 100644
--- a/ideas/index.rst
+++ b/ideas/index.rst
@@ -7,8 +7,11 @@ Below are the project ideas for the GSoC 2024 sorted for better navigation. The
with experts on building open source embedded systems. An embedded system is build of computers
dedicated a specific collections of functions and connected to automate things in the physical world.
-.. note:: Discussion for all projects will be done via `forum <https://forum.beagleboard.org/>`_
- and must be open for all participants (no DMs allowed).
+.. important::
+ BeagleaBoard.org is a community centric organization and we keep all of our discussion open for our
+ community on `forum <https://forum.beagleboard.org/>`_. Discussion for all the ideas/projects will
+ be done via `forum <https://forum.beagleboard.org/>`_ as well and must be open for everyone to access. **No
+ direct messages should be sent to mentors or community members until unless there is a private matter.**
All the projects have colorful badges for making your choice easier,
--
GitLab