diff --git a/.github/workflows/code-review.yaml b/.github/workflows/code-review.yaml new file mode 100644 index 0000000..f62276a --- /dev/null +++ b/.github/workflows/code-review.yaml @@ -0,0 +1,40 @@ +name: Code Review Bot + +on: + pull_request: + types: [opened, reopened, synchronize] + +jobs: + run_code_review_bot: + runs-on: ubuntu-latest + + container: + image: ghcr.io/mrs-electronics-inc/bots/code-review:latest + volumes: + - ${{ github.workspace }}:/repo + + defaults: + run: + working-directory: /repo + + permissions: + pull-requests: write + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Code Review Bot + env: + OPENROUTER_KEY: ${{ secrets.API_KEY_CODE_REVIEW_BOT }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }} + run: github_code_review.sh + + - name: Upload artifact including hidden files + uses: actions/upload-artifact@v4 + with: + name: bots-directory + path: .bots/ + include-hidden-files: true + diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml new file mode 100644 index 0000000..c2838e0 --- /dev/null +++ b/.github/workflows/deploy.yaml @@ -0,0 +1,34 @@ +name: Deploy to GitHub Pages + +on: + # Trigger the workflow every time you push to the `main` branch + push: + branches: [ main ] + # Allows you to run this workflow manually from the Actions tab on GitHub. + workflow_dispatch: + +# Allow this job to clone the repo and create a page deployment +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout your repository using git + uses: actions/checkout@v4 + - name: Install, build, and upload your site + uses: withastro/action@v3 + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/astro.config.mjs b/astro.config.mjs index 9714543..0cb37da 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -5,22 +5,19 @@ import starlightBlog from 'starlight-blog' // https://astro.build/config export default defineConfig({ + site: "https://mrs-electronics.dev", integrations: [ starlight({ plugins: [starlightBlog()], - title: 'My Docs', - social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }], + title: 'MRS Developers', + social: [ + { icon: 'github', label: 'GitHub', href: 'https://github.com/mrs-electronics-inc' }, + { icon: 'gitlab', label: 'GitLab', href: 'https://gitlab.com/mrs-electronics' }, + ], sidebar: [ { - label: 'Guides', - items: [ - // Each item here is one entry in the navigation menu. - { label: 'Example Guide', slug: 'guides/example' }, - ], - }, - { - label: 'Reference', - autogenerate: { directory: 'reference' }, + label: 'Blog', + autogenerate: { directory: 'blog' }, }, ], }), diff --git a/public/apple-touch-icon.png b/public/apple-touch-icon.png new file mode 100644 index 0000000..1b8b045 Binary files /dev/null and b/public/apple-touch-icon.png differ diff --git a/public/favicon-96x96.png b/public/favicon-96x96.png new file mode 100644 index 0000000..c9b616e Binary files /dev/null and b/public/favicon-96x96.png differ diff --git a/public/favicon.ico b/public/favicon.ico new file mode 100644 index 0000000..7308d6e Binary files /dev/null and b/public/favicon.ico differ diff --git a/public/favicon.svg b/public/favicon.svg index cba5ac1..37bf3b0 100644 --- a/public/favicon.svg +++ b/public/favicon.svg @@ -1 +1,41 @@ - \ No newline at end of file + + + + + + + + + + + + + + + RAL: 5015RGB: 35, 114, 181CMYK: 84, 49, 3, 0#2372b5 + \ No newline at end of file diff --git a/public/site.webmanifest b/public/site.webmanifest new file mode 100644 index 0000000..e0b8916 --- /dev/null +++ b/public/site.webmanifest @@ -0,0 +1,21 @@ +{ + "name": "MRS Developers", + "short_name": "MRS Devs", + "icons": [ + { + "src": "/web-app-manifest-192x192.png", + "sizes": "192x192", + "type": "image/png", + "purpose": "maskable" + }, + { + "src": "/web-app-manifest-512x512.png", + "sizes": "512x512", + "type": "image/png", + "purpose": "maskable" + } + ], + "theme_color": "#2272b4", + "background_color": "#ffffff", + "display": "standalone" +} \ No newline at end of file diff --git a/public/web-app-manifest-192x192.png b/public/web-app-manifest-192x192.png new file mode 100644 index 0000000..7a64f07 Binary files /dev/null and b/public/web-app-manifest-192x192.png differ diff --git a/public/web-app-manifest-512x512.png b/public/web-app-manifest-512x512.png new file mode 100644 index 0000000..bb28564 Binary files /dev/null and b/public/web-app-manifest-512x512.png differ diff --git a/src/assets/MRS-Logo.png b/src/assets/MRS-Logo.png new file mode 100644 index 0000000..3234ab3 Binary files /dev/null and b/src/assets/MRS-Logo.png differ diff --git a/src/assets/houston.webp b/src/assets/houston.webp deleted file mode 100644 index 930c164..0000000 Binary files a/src/assets/houston.webp and /dev/null differ diff --git a/src/content/docs/blog/docs-repo-vs-wiki.md b/src/content/docs/blog/docs-repo-vs-wiki.md new file mode 100644 index 0000000..3c0a1f1 --- /dev/null +++ b/src/content/docs/blog/docs-repo-vs-wiki.md @@ -0,0 +1,70 @@ +--- +title: Should I Really Use a Gitlab Wiki? +date: 2025-03-14 +authors: + name: Bennett Moore + title: Software Developer + picture: https://avatars.githubusercontent.com/u/120052232?s=400&u=0c610467b3f8295f904f0c81c97214217def6020&v=4 +--- + +Recently, as we've been taking on new software projects and continuing to develop existing ones, the role of documentation has come into focus. + +In fact, the development of this very site is a direct result of an increased focus by our whole software team to better document the things we learn and already know. + +But...WHERE should all this information go? In the past, we always defaulted to Gitlab wikis...but is that the best option? Would an dedicated documentation repository for each project make more sense? + +I will note that if your project uses a monorepo, I will think of "dedicated repo" as meaning "dedicated folder inside the repo"; something like `apps/docs` will work just fine and function the same as a separate repo in a multi-repo project structure. + +## Gitlab Wiki: Pros + +The Gitlab wiki feature is really a very powerful one. Every group and repository is **automatically given a wiki** (unless it's disabled in the project settings), so there's no additional setup required. + +Wikis are designed to be very **quick and easy to contribute to**. Internally, they are based on a Git repo, but you don't have to clone the repo or worry about local copies or anything; Gitlab allows you to make and commit all your edits right from the UI and then does the Git operations behind the scenes. + +Wikis support **easy file uploads** for images, PDFs, and whatever else in much the same way that other features do (like uploading files to an issue or MR description). You can attach the file and Gitlab automatically stores it for you with no extra configuration needed. + +## Gitlab Wiki: Cons + +Gitlab wikis also have some negatives that come with them. + +First, these automatic wikis are nice, but they can quickly result in **splintered, spread out documentation**. It's very common for one "project" to consist of a group of multiple projects. If each one has its own wiki, including the top-level group, then which one should the project's documentation go in? + +This quickly becomes a problem when you have multiple developers adding things to different wikis. Not only is it likely that some of the more general information will be duplicated, which means unnecessary work, but it also becomes hard to know which wiki is the central source of truth. If two wikis have conflicting information, which version of the information should you choose as being true? You'll have to ask someone else to confirm, which only serves to take more time for both of you. + +Having multiple wikis requires you to remember which one has which pieces of information, which can quickly become a headache when trying to point other team members to something. + +The only real way to avoid this problem is to establish from the start which wiki will be the central source of truth and disable the other wikis entirely. + +Another disadvantage is a **lack of peer review**. Gitlab wikis are easy to contribute to...but that can also be a negative, because no outside approval is required to make changes. Anyone on the team can write down whatever they want and the only way for erroneous documentation to be discovered is if another team member stumbles across it and recognizes the error. + +Gitlab wikis are also just that--Gitlab wikis. They're **tied to Gitlab**. If your project is ever migrated to another code-hosting or issue-tracking site, such as Jira/Bitbucket or Github, then you'll have to do some work to migrate the wiki with it. It's fairly easy to clone the wiki's internal repo and push that to the new site, but you'll have to go through and update all the Gitlab-specific parts: for example, those lovely file uploads that I mentioned earlier? You'll have to download each file, change the link that points to it, and figure out a simple way of storing those files in the repo. + +## Dedicated Repo: Pros + +There are a lot of advantages to using a dedicated separate repository for documentation. One of the biggest ones is **peer review**. By creating a separate repository (and setting up the typical workflow, with MRs, protected branches, required approvals, and the like), you force all new documentation to be reviewed by another member of the team. + +There are a multitude of reasons why this is a good thing that boil down to the reasons why _any_ peer review on code is a good thing. Reviewers can test any deployment/setup steps that are documented to make sure they work correctly; they can filter information that isn't really worth documenting; they can suggest spots where more clarity or explanation might be needed; and so on. Code review is core to the functioning of any well-managed project, and documentation must be held to the same rigorous standard. + +Another big, closely related advantage is **real version control**. The Gitlab wiki does use an internal repo, but when editing through the UI, it's as if every change you make is a push straight to `main` (which, as any good developer knows, is NOT a good practice). I've seen multiple occasions where someone was trying to edit a wiki page at the same time as someone else and their changes conflicted. + +With a dedicated repo, this abstraction of easy changes is removed, and that's a good thing. Team members can check out their own branches to modify content and make sure all their edits are complete and concise. If someone is working on a big new feature, they can make a separate branch of the documentation where they document their new feature as they implement it. While this does require maintaining multiple MRs, we find that to be a small tradeoff for the benefits it brings. + +Using a separate repo also simplifies the task of **deployment to an external location**. For example, if you want to use [Starlight](https://starlight.astro.build/) (hint: that's what we used for this site!) to create an actual website for the project documentation, then it's _easy_ to do so. You can set up the Starlight project in the repository, configure the CI/CD deployments, and so on. + +This becomes very important when you want customers to be able to see some or all of the documentation. Gitlab wikis have the same visibility as the project they are a part of; if the project is private (as the majority of ours are), then the wiki is also private. You can't link to the wiki when talking to customers unless they are made a member of the project, which is its own can of worms...suffice to say it is a can of worms that SHOULD NOT be opened. So, for customers to get access to useful information, you'll have to have some way of deploying it outside of the project. + +Having a separate repo also gives you much more **structural freedom**. You can define the hierarchy of files however you want, use whatever file formats/types you want, and so forth. For example, in one of my projects, the documentation repo contains both an external site and an internal "wiki". The external site is for things that we want the customer to be able to access, and the internal wiki is for more development-centric things: running tests, working with hardware, meeting notes, and the like. Having "docs" for external documentation and a "wiki" for internal documentation is a pattern that has served our team well across multiple projects. + +## Dedicated Repo: Cons + +One of the only real "cons" to a dedicated repo is that it takes slightly **longer to make changes** as compared to a Gitlab wiki, but this is only a con if you don't care about review. We care about making sure documentation is correct and complete and thus much appreciate the slightly slower turnaround time for pushing new information to customers. + +It can also be tedious to have to **manage MRs in multiple repos**; if you implement a new feature in the actual project repo, and then provide documentation for said feature in the docs repo, you now have two MRs to complete one feature. + +However, this isn't a big issue...wikis effectively require the same thing because you are still updating the documentation in a spot that is not the project repo. Plus, if your project uses a monorepo, then the problem is avoided entirely and in fact becomes even more streamlined because the documentation changes and feature changes can be reviewed in a single MR. + +## Conclusions + +We have found using a dedicated separate repository for documentation to be far preferable to using a Gitlab wiki in the projects here at MRS. While this doesn't mean that it's the unquestioned best solution for every project, the majority of projects will likely benefit from this structure. + +A dedicated repo is much more flexible in terms of deployment and structure, allows for real peer review, and avoids problems with splintered docs in more than one place and over-reliance on Gitlab. If you're going to be creating a new project anytime soon, we recommend creating your documentation repo right from the start. diff --git a/src/content/docs/blog/lessons-from-2024.md b/src/content/docs/blog/lessons-from-2024.md new file mode 100644 index 0000000..43fe482 --- /dev/null +++ b/src/content/docs/blog/lessons-from-2024.md @@ -0,0 +1,78 @@ +--- +title: Lessons from 2024 +date: 2025-01-10 +authors: + name: Addison Emig + title: Software Engineer + picture: https://avatars.githubusercontent.com/u/17209828?s=200 +--- + +2024 was quite the year for learning new things! It wasn't very comfortable, but I definitely learned a lot. + +## Combining teams is challenging + +_but can produce great value when done well_ + +The learning of this lesson took up the first eight months of the year for me. I was given most of the responsibility for merging the Spoke.Zone and Lenticul dev teams into one combined Spoke.Zone dev team. It was something I dreaded quite a bit at first, but with time I began to see the benefits. I'm really glad I went through this process. I think it was a good opportunity to grow as a leader in a way that really stretched me. + +### Challenges + +#### Combining Processes + +The Lenticul team and Spoke.Zone teams had **very** different processes in place before the merge, especially in regard to the development life cycle and release management. + +A few examples: + +- The Lenticul team used Jira for issue management, while the Spoke.Zone team used GitLab. +- The Lenticul team had a dedicated QA tester, while the Spoke.Zone team had very underdeveloped testing practices. +- The Lenticul team had a large amount of staging environments, while the Spoke.Zone team only had one. + +In situations like these, it is easy to think that your status quo is the best, and that the incoming team members should adjust to your processes. However, this is not the best strategy. It is much better (though it takes much more work) to carefully consider all parts of your processes and develop new team processes that build on the strengths of the process of both of the teams. + +#### Developing Solid Communication + +Solid communication is vital to any team. For a while, the Lenticul and Spoke.Zone teams worked together but apart. We hadn't defined the communication channels very well, so we continued to operate as two independent teams. This created a lot of unnecessary delay and misunderstandings. Having shared communication channels is vital for integrating two teams into one team. Without good communication, a team will struggle to make forward progress. + +#### Building Trust + +My goal for the Spoke.Zone team has always been to develop an autonomous team, one that doesn't require a lot of direct supervision. This requires a lot of trust among the team members. Building this trust takes quite a while. It is easy to get frustrated with colleagues that don't seem to be working towards the team's goals. In situations like these, it is important to do a self-evaluation. Do you have unreasonable expectations? Have the goals been communicated well? Have you done your best to communicate one-on-one with your colleague to resolve the misunderstandings? + +### Benefits + +A merger of two teams takes a lot of effort, and you don't usually see the benefits right away. + +It took me some time to realize some of these, but once I did it made all the work we put into the merger worth it. + +#### Greater Combined Experience + +This one is pretty simple. The more team members you have, the more combined experience you will have on the team. This means it is more likely that one of people on the team will have some experience with a new technology you are introducing to the team, allowing them to take the lead in implementing the improvements. + +#### Greater Ability to Fill Gaps + +None of us are a complete and perfect package. We all have gaps in our skill set and knowledge base. The more team members you have, the easier it becomes to fill in each other's gaps. This does require good communication to discover and resolve those gaps. + +#### New Perspectives + +We all come from different backgrounds and have experiences with different things. It is possible for different perspectives to create conflicts. However, on a healthy team these diverse perspectives can be used to refine ideas, allowing you to develop much better designs. + +## We make our living by meeting our customers' needs + +_not by producing engineering perfection_ + +I am a serial perfectionist. It is quite easy for me to fall down the dangerous rabbit hole of perfecting and refining a feature than nobody ends up using. In 2024, I got the blessing of several deadlines that prevented me from falling down this rabbit hole. I also got the chance to interact more directly with some of our customers. This gave me the opportunity to hear things from their perspective, to learn about the problems they need solved. One of my goals going forward is to be much more intentional about seeking out the customers' needs and prioritizing accordingly. + +A perfect solution for the wrong problem is useless to the customer. + +## We should never take our colleagues for granted + +_we might not work together next week_ + +This was the most painful lesson to learn. Within the space of about four months, we lost three engineers from our software team. Also in the middle of that time, the Spoke.Zone team lost two engineers that were employed by our contractor, Supportronics. It really made me realize that often job satisfaction has less to do with **what** you are working on, and rather **who** you are working with. + +It's very easy to take your colleagues for granted, to get this mental image that they will just always be there. Of course, we know this isn't true, but I realized that I often went about with this kind of mindset. + +It is important to take time to appreciate your colleagues. Let them know that you value their work and the impact they have had on your life and career. They won't be around for ever. + +## Conclusion + +Growth doesn't really come without some pain, but I do hope 2025 is a year of a bit less pain. Losing close colleagues can be a pretty painful thing, however it is also a chance to learn and re-evaluate. One thing is for certain, we can't read the future! Hopefully our software team can grow stronger in 2025 with the lessons we learned in 2024! diff --git a/src/content/docs/guides/example.md b/src/content/docs/guides/example.md deleted file mode 100644 index ebd0f3b..0000000 --- a/src/content/docs/guides/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Guide -description: A guide in my new Starlight docs site. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 664b681..44f5179 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,36 +1,28 @@ --- -title: Welcome to Starlight -description: Get started building your docs site with Starlight. +title: MRS Developers +description: The home page for MRS developer content. template: splash hero: - tagline: Congrats on setting up a new Starlight project! + tagline: The home page for MRS developer content! image: - file: ../../assets/houston.webp + file: ../../assets/MRS-Logo.png actions: - - text: Example Guide - link: /guides/example/ + - text: Blog + link: /blog icon: right-arrow - - text: Read the Starlight docs - link: https://starlight.astro.build - icon: external - variant: minimal --- -import { Card, CardGrid } from '@astrojs/starlight/components'; +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; -## Next steps +## Useful Links - - Edit `src/content/docs/index.mdx` to see this page change. + + + - - Add Markdown or MDX files to `src/content/docs` to create new pages. - - - Edit your `sidebar` and other config in `astro.config.mjs`. - - - Learn more in [the Starlight Docs](https://starlight.astro.build/). + + + diff --git a/src/content/docs/reference/example.md b/src/content/docs/reference/example.md deleted file mode 100644 index 0224f09..0000000 --- a/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework