diff --git a/README.md b/README.md index a5e390e57..100e57d13 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ take up to 60 seconds once the docker build finishes. ### Recommended - Install git commit template: [Commit Template](docs/commit.template.md). +- Docker Commands: [Docker Commands](docs/docker.md). +- Git Conventions: [Git Conventions](docs/git-convention.md). +- Volta: [Volta](#volta) ### Optional @@ -48,329 +51,3 @@ npm run test:check-coverage-thresholds OSF uses volta to manage node and npm versions inside of the repository Install Volta from https://volta.sh/ and it will automatically pin Node/npm per the repo toolchain. - -## Docker - -The OSF angular project uses a docker image to simplify that developer process. - -### Volumes - -The container serves and rebuilds from mounted sources. The following host paths -are mounted into the container’s workdir (e.g., `/app`): - -- `./public` → `/app/public` -- `./src` → `/app/src` -- `./angular.json` → `/app/angular.json` -- `./tsconfig.json` → `/app/tsconfig.json` -- `./tsconfig.app.json` → `/app/tsconfig.app.json` - -**Notes:** - -1. `node_modules` is installed **inside the image** during build; it is **not** mounted from the host. -2. The `start:docker` command runs the Angular CLI build and development server inside the container. - It requires the project’s Angular configuration files (`angular.json`, `tsconfig.json`, `tsconfig.app.json`) to be present in the container’s `/app` directory. - If these are missing, the container will fail to build or serve the app. - -### Angular server - -The angular server is run from the docker image. -localhost:4200 in any browser will display the site. -Any changes to files in the /root/src directory will force the angular server to reload - -The dev server binds to `0.0.0.0` inside the container so your host can reach it on `http://localhost:4200`. -If you don’t see the site, ensure the start script includes: - -```json -"start": "ng serve --host 0.0.0.0 --port 4200 --poll 2000" -``` - -### Docker Commands - -#### build + run in background (build is only required for the initial install or npm updates) - -```bash -docker compose up -d --build -``` - -#### run in background - -```bash -docker compose up -d -``` - -#### stop the container - -```bash -docker compose stop -``` - -#### stop & remove the container(s) - -```bash -docker compose down -v -``` - -#### Verify the image is running - -```bash -docker compose ps -``` - -#### Stream the web logs after viewing the last 200 - -```bash -docker compose logs -f web --tail=200 -``` - -```md -(`--tail=200` shows the last 200 lines first, `-f` follows new output.) -``` - -#### get a shell in the container if needed - -```bash -docker exec -it angular-dev sh -``` - -#### List all Docker images - -```bash -docker images -``` - -#### Remove a specific image by IMAGE ID - -```bash -docker rmi -``` - -#### Remove a specific image by name:tag - -```bash -docker rmi : -``` - -#### Force remove (if image is in use) - -```bash -docker rmi -f -``` - -#### Troubleshooting - -If the application does not open in your browser at [http://localhost:4200](http://localhost:4200), follow these steps in order: - -1. **Check if the container is running** - - ```bash - docker compose ps - ``` - - Look for the `web` container and verify its status is `Up`. - -2. **Rebuild and recreate the container** - If the container is not running, has exited, or the image is outdated: - - ```bash - docker compose up --build -d - ``` - -3. **View container logs for errors** - - ```bash - docker compose logs web - ``` - -4. **Test if the service responds locally** - - ```bash - curl http://localhost:4200 - ``` - - You should see HTML output from the Angular app. - -5. **Verify that port 4200 is bound** - - ```bash - docker compose port web 4200 - ``` - - This should return something like `0.0.0.0:4200` or `127.0.0.1:4200`. - -6. **Bypass browser caching issues** - - - Open the site in an incognito/private window. - - Or test with: - ```bash - curl -I http://localhost:4200 - ``` - -7. **Check network configuration** - Ensure the web container is connected to the correct network: - - ```bash - docker network ls - docker network inspect - ``` - -8. **Inspect live Angular CLI logs** - If Angular is not serving content, run: - - ```bash - docker compose exec web npm run start:docker -- --verbose - ``` - -9. **If all else fails – reset and rebuild everything** - ```bash - docker compose down --volumes --remove-orphans - docker compose up --build -d - ``` - -## rollup issues and 2 package-lock.json file. - -Due to a Rollup build quirk, the Docker image generates its own package-lock.json that may differ from the host version. We keep both the host and Docker-generated lock files to ensure consistent installs in each environment and to avoid dependency mismatches during builds. - -The files are: - -- package-lock.json - used for local development -- package-lock.docker.json - used for docker - -### How to copy the lock file out of the image - -1. **Build the image** (this will create the lock file inside it): - - ```sh - docker build -t osf-angular-dev . - ``` - -2. **Create a container from it** (don’t start it): - - ```sh - docker create --name temp-angular osf-angular-dev - ``` - -3. **Copy the file from the container to your host**: - - ```sh - docker cp temp-angular:/app/package-lock.json ./package-lock.docker.json - ``` - -4. **Remove the container**: - ```sh - docker rm temp-angular - ``` - -## Commitlint - -OSF uses [Commitlint](https://www.npmjs.com/package/commitlint) to **enforce a consistent commit message format**. -This helps ensure that every commit clearly communicates its purpose, makes the Git history easier to read, and supports automated release notes. - -Commitlint is configured to follow the **[Conventional Commits](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)** specification. -Before committing changes, please review the [config-conventional README](https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/config-conventional/README.md) for the complete standard. - ---- - -### **Commit Message Structure** - -Commit messages must be structured as: - -``` -[scope]: - -[optional body] - -[optional footer(s)] -``` - -- **`type`** → Describes the category of change (**required**). -- **`scope`** → Indicates the section of the codebase affected (**recommended**). -- **`description`** → A concise summary of the change (**required**, lowercase, no period at the end). -- **`body`** → More detailed explanation of the change (**optional**). -- **`footer`** → Metadata such as breaking change notices or issue references (**optional**). - ---- - -### **Allowed Commit Types** - -| Type | Description | -| ------------ | ------------------------------------------------------------------------------------- | -| **feat** | New feature added to the codebase. | -| **fix** | Bug fix for an existing issue. | -| **docs** | Documentation-only changes (e.g., README, comments). | -| **style** | Changes that do not affect code meaning (formatting, whitespace, missing semicolons). | -| **refactor** | Code restructuring without changing external behavior. | -| **perf** | Code changes that improve performance. | -| **test** | Adding or updating tests. | -| **chore** | Changes to the build process, CI/CD pipeline, or dependencies. | -| **revert** | Reverts a previous commit. | - ---- - -### **Examples** - -✅ **Good Examples** - -``` -feat(auth): add OAuth2 login support -fix(user-profile): resolve avatar upload failure on Safari -docs(readme): add setup instructions for Windows -style(header): reformat nav menu CSS -refactor(api): simplify data fetching logic -perf(search): reduce API response time by caching results -test(auth): add tests for password reset flow -chore(deps): update Angular to v19 -revert: revert “feat(auth): add OAuth2 login support” -``` - -❌ **Bad Examples** - -``` -fixed bug in login -added feature -update stuff -``` - ---- - -### **Helpful Hints** - -- Keep descriptions short (**under 100 characters**) and clear. -- Use imperative mood (“add feature” not “added feature”). -- Use scopes to make history easier to navigate (`feat(auth): ...`, `fix(api): ...`). -- For **breaking changes**, include a footer: - ``` - BREAKING CHANGE: description of the change and migration instructions - ``` -- Link related issues in the footer using: - ``` - Closes #123 - Refs #456 - ``` - ---- - -Commitlint will run automatically and reject non-compliant messages. - -## GitHub pipeline - -The `.github` folder contains the following: - -1. The test run "counter" scripts - .github/counter -2. Script needed for the deployment process - .github/scripts -3. The GitHub action workflow scripts - .github/workflows -4. The GitHub PR templates - .github/pull_request_template.md - -## Local pipeline - -The local pipeline is managed via husky - -1. The pre-commit requirements are: - - linting on the staged files passes - - .husky/pre-commit -2. The pre-push requirements are: - - All tests pass - - Test coverage is met diff --git a/docs/admin.knowledge-base.md b/docs/admin.knowledge-base.md index ea541ee06..15d8adf5a 100644 --- a/docs/admin.knowledge-base.md +++ b/docs/admin.knowledge-base.md @@ -4,6 +4,31 @@ Information on updates that require admin permissions ## All things GitHub +### GitHub pipeline + +The `.github` folder contains the following: + +1. The test run "counter" scripts + .github/counter +2. Script needed for the deployment process + .github/scripts +3. The GitHub action workflow scripts + .github/workflows +4. The GitHub PR templates + .github/pull_request_template.md + +### Local pipeline + +The local pipeline is managed via husky + +1. The pre-commit requirements are: + - linting on the staged files passes + - .husky/pre-commit +2. The pre-push requirements are: + - All tests pass + - Test coverage is met + - .husky/pre-push + ### Updating the git template message if the shared template changes in `.github/templates/commit-template.txt`, pull the latest changes from `main` and you’ll get the updated version automatically. your local git config will still point to the same file. diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 000000000..6cb529323 --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,176 @@ +# Docker + +The OSF angular project uses a docker image to simplify the developer process. + +### Volumes + +The container serves and rebuilds from mounted sources. The following host paths +are mounted into the container’s workdir (e.g., `/app`): + +- `./public` → `/app/public` +- `./src` → `/app/src` +- `./angular.json` → `/app/angular.json` +- `./tsconfig.json` → `/app/tsconfig.json` +- `./tsconfig.app.json` → `/app/tsconfig.app.json` + +**Notes:** + +1. `node_modules` is installed **inside the image** during build; it is **not** mounted from the host. +2. The `start:docker` command runs the Angular CLI build and development server inside the container. + It requires the project’s Angular configuration files (`angular.json`, `tsconfig.json`, `tsconfig.app.json`) to be present in the container’s `/app` directory. + If these are missing, the container will fail to build or serve the app. + +### Angular server + +The angular server is run from the docker image. +localhost:4200 in any browser will display the site. +Any changes to files in the /root/src directory will force the angular server to reload + +The dev server binds to `0.0.0.0` inside the container so your host can reach it on `http://localhost:4200`. +If you don’t see the site, ensure the start script includes: + +```json +"start": "ng serve --host 0.0.0.0 --port 4200 --poll 2000" +``` + +## Docker Commands + +### build + run in background (build is only required for the initial install or npm updates) + +```bash +docker compose up -d --build +``` + +### run in background + +```bash +docker compose up -d +``` + +### stop the container + +```bash +docker compose stop +``` + +### stop & remove the container(s) + +```bash +docker compose down -v +``` + +### Verify the image is running + +```bash +docker compose ps +``` + +### Stream the web logs after viewing the last 200 + +```bash +docker compose logs -f web --tail=200 +``` + +```md +(`--tail=200` shows the last 200 lines first, `-f` follows new output.) +``` + +### get a shell in the container if needed + +```bash +docker exec -it angular-dev sh +``` + +### List all Docker images + +```bash +docker images +``` + +### Remove a specific image by IMAGE ID + +```bash +docker rmi +``` + +### Remove a specific image by name:tag + +```bash +docker rmi : +``` + +### Force remove (if image is in use) + +```bash +docker rmi -f +``` + +## Troubleshooting + +If the application does not open in your browser at [http://localhost:4200](http://localhost:4200), follow these steps in order: + +1. **Check if the container is running** + + ```bash + docker compose ps + ``` + + Look for the `web` container and verify its status is `Up`. + +2. **Rebuild and recreate the container** + If the container is not running, has exited, or the image is outdated: + + ```bash + docker compose up --build -d + ``` + +3. **View container logs for errors** + + ```bash + docker compose logs web + ``` + +4. **Test if the service responds locally** + + ```bash + curl http://localhost:4200 + ``` + + You should see HTML output from the Angular app. + +5. **Verify that port 4200 is bound** + + ```bash + docker compose port web 4200 + ``` + + This should return something like `0.0.0.0:4200` or `127.0.0.1:4200`. + +6. **Bypass browser caching issues** + + - Open the site in an incognito/private window. + - Or test with: + ```bash + curl -I http://localhost:4200 + ``` + +7. **Check network configuration** + Ensure the web container is connected to the correct network: + + ```bash + docker network ls + docker network inspect + ``` + +8. **Inspect live Angular CLI logs** + If Angular is not serving content, run: + + ```bash + docker compose exec web npm run start:docker -- --verbose + ``` + +9. **If all else fails – reset and rebuild everything** + ```bash + docker compose down --volumes --remove-orphans + docker compose up --build -d + ``` diff --git a/docs/git-convention.md b/docs/git-convention.md index 9536e0628..d0c99b2b4 100644 --- a/docs/git-convention.md +++ b/docs/git-convention.md @@ -1,10 +1,166 @@ -# 📌 Git Branch Naming Convention (Aligned with Angular Guideline) +# CommitLint and Git Branch Naming Convention (Aligned with Angular Guideline) -# 📖 Introduction +To maintain a clean, structured commit history and optimize team collaboration, we adhere to the Angular Conventional Commits standard for both commit messages and Git branch naming. This ensures every change type is immediately recognizable and supports automation for changelog generation, semantic versioning, and streamlined release processes. -### To maintain a clean commit history and improve team collaboration, we follow Angular Conventional Commits in our Git branch naming. This approach makes it easy to identify change types and automate release processes. +In addition, we enforce these standards using CommitLint, ensuring that all commit messages conform to the defined rules before they are accepted into the repository. -# 🚀 Branch Naming Format +This project employs both GitHub Actions and a local pre-commit pipeline to validate commit messages, enforce branch naming conventions, and maintain repository integrity throughout the development workflow. + +## Local pipeline + +The local pipeline is managed via husky + +1. The pre-commit requirements are: + - linting on the staged files passes +2. The pre-push requirements are: + - All tests pass + - Test coverage is met + +## Contributing Workflow + +To contribute to this repository, follow these steps: + +1. **Fork the Repository** + + - Go to the main repository page on GitHub [OSF Angular Project](https://github.com/CenterForOpenScience/angular-osf). + - Click the **Fork** button (top-right corner). + - This creates a copy of the repository under your GitHub account. + +2. **Clone Your Fork** + + ```bash + git clone https://github.com//.git + cd + ``` + +3. **Create a Feature Branch** + + ```bash + git checkout -b feat/my-new-feature + ``` + +4. **Make Your Changes** + + - Follow the commit conventions outlined below. + - Ensure all tests pass before committing. + +5. **Push to Your Fork** + + ```bash + git push origin feat/my-new-feature + ``` + +6. **Open a Pull Request** + - Go to the main repository page on GitHub [OSF Angular Project](https://github.com/CenterForOpenScience/angular-osf). + - Click **New Pull Request**. + - Select your fork and branch, then create the PR against the appropriate branch of the main repo. + - A pre-determined `feature` branch (standard OSF development cycle) + - The `active PB&S` branch (standard OSF bug fix cycle) + - `develop` (used by internal OSF release engineers for releases to the testing environment) + - `main` (used by internal OSF release engineers to push tested (QA and UAT) code to production) + +--- + +This workflow ensures that: + +- All changes are reviewed before merging. +- The main repository remains stable. +- Contributors maintain full control of their own changes until they are merged. + +For a step-by-step guide on forking and creating pull requests, see [GitHub’s documentation on forks](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and [about pull requests](https://docs.github.com/en/pull-requests). + +## Commitlint + +OSF uses [Commitlint](https://www.npmjs.com/package/commitlint) to **enforce a consistent commit message format**. +This helps ensure that every commit clearly communicates its purpose, makes the Git history easier to read, and supports automated release notes. + +Commitlint is configured to follow the **[Conventional Commits](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)** specification. +Before committing changes, please review the [config-conventional README](https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/config-conventional/README.md) for the complete standard. + +--- + +### **Commit Message Structure** + +Commit messages must be structured as: + +``` +[scope]: + +[optional body] + +[optional footer(s)] +``` + +- **`type`** → Describes the category of change (**required**). +- **`scope`** → Indicates the section of the codebase affected (**recommended**). +- **`description`** → A concise summary of the change (**required**, lowercase, no period at the end). +- **`body`** → More detailed explanation of the change (**optional**). +- **`footer`** → Metadata such as breaking change notices or issue references (**optional**). + +--- + +### **Allowed Commit Types** + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------- | +| **feat** | New feature added to the codebase. | +| **fix** | Bug fix for an existing issue. | +| **docs** | Documentation-only changes (e.g., README, comments). | +| **style** | Changes that do not affect code meaning (formatting, whitespace, missing semicolons). | +| **refactor** | Code restructuring without changing external behavior. | +| **perf** | Code changes that improve performance. | +| **test** | Adding or updating tests. | +| **chore** | Changes to the build process, CI/CD pipeline, or dependencies. | +| **revert** | Reverts a previous commit. | + +--- + +### **Examples** + +✅ **Good Examples** + +``` +feat(auth): add OAuth2 login support +fix(user-profile): resolve avatar upload failure on Safari +docs(readme): add setup instructions for Windows +style(header): reformat nav menu CSS +refactor(api): simplify data fetching logic +perf(search): reduce API response time by caching results +test(auth): add tests for password reset flow +chore(deps): update Angular to v19 +revert: revert “feat(auth): add OAuth2 login support” +``` + +❌ **Bad Examples** + +``` +fixed bug in login +added feature +update stuff +``` + +--- + +### **Helpful Hints** + +- Keep descriptions short (**under 100 characters**) and clear. +- Use imperative mood (“add feature” not “added feature”). +- Use scopes to make history easier to navigate (`feat(auth): ...`, `fix(api): ...`). +- For **breaking changes**, include a footer: + ``` + BREAKING CHANGE: description of the change and migration instructions + ``` +- Link related issues in the footer using: + ``` + Closes #123 + Refs #456 + ``` + +--- + +Commitlint will run automatically and reject non-compliant messages. + +## Branch Naming Format ### The branch name should follow the format: @@ -19,26 +175,11 @@ short-description – a brief description of the change. ``` -# 📌 Available Types (type) - -### We use the following types to categorize changes: +## Available Types (type) -```bash -| Type --- Purpose -| feat --- Adding a new feature -| fix --- Fixing a bug or issue -| refactor --- Code refactoring without changing functionality -| perf --- Performance improvements -| test --- Adding or updating tests -| chore --- Updating configurations, tools, or dependencies -| docs --- Updating or adding documentation -| style --- Code style changes (formatting, indentation, comments) -| ci --- Changes in CI/CD pipeline -| build --- Updates in build process or dependencies -| revert --- Reverting previous changes -``` +See the [Allowed Commit Types](#allowed-commit-types) section for details. -# 📝 Branch Naming Examples +## Branch Naming Examples ### Here are some examples of branch names: @@ -51,16 +192,16 @@ short-description – a brief description of the change. ``` -# 🛠 Example of Creating a Branch: +### 🛠 Example of Creating a Branch: -### To create a new branch, use the following command: +To create a new branch, use the following command: ```bash git checkout -b feat/1234-add-user-authentication ``` -# 🏆 Best Practices +### 🏆 Best Practices - ✅ Use short and clear descriptions in branch names. - ✅ Follow a consistent style across all branches for better project structure. @@ -68,7 +209,7 @@ git checkout -b feat/1234-add-user-authentication - ✅ Use kebab-case (- instead of \_ or CamelCase). - ✅ If there is no issue ID, omit it, e.g., docs/update-contributing-guide. -# 🔗 Additional Resources +### 🔗 Additional Resources **Conventional Commits**: https://www.conventionalcommits.org @@ -76,52 +217,9 @@ git checkout -b feat/1234-add-user-authentication **Git Flow**: https://nvie.com/posts/a-successful-git-branching-model/ -# This branch naming strategy ensures better traceability and improves commit history readability. 🚀 - -# 📝 Commit Message Formatting - -To ensure clear and structured commit messages, we follow the Conventional Commit format: - -🔹 **Commit Message Structure** - -```bash -(): - -[optional body] - -[optional footer] - -type – The type of change (e.g., feat, fix, docs, style, etc.). - -scope – A short context describing the part of the project affected (optional but recommended). - -short description – A concise summary of the change (in imperative form, e.g., "fix login bug"). - -body – A more detailed explanation of the change (if necessary). - -footer – Additional metadata, e.g., references to issues (Closes #123). -``` - -# 📌 Example Commit Messages - -```bash - -feat(auth): add user authentication flow - -Implemented login, registration, and session handling. -Closes #1234. - -fix(ui): resolve button alignment issue - -Fixed misalignment of buttons in the settings panel. - -docs(readme): update installation instructions - -Clarified step-by-step setup instructions for the project. - -``` +### This branch naming strategy ensures better traceability and improves commit history readability. -# 🔗 Additional Resources +### 🔗 Additional Resources Conventional Commits: https://www.conventionalcommits.org